Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

wip: ai auto feedback ai editing improvements (#5511)

Wolf Mermelstein7ded7ca908d1
diff --git a/apps/web/patches/[email protected] b/apps/web/patches/[email protected]
new file mode 100644
index 0000000000..30bac18733
--- /dev/null
+++ b/apps/web/patches/[email protected]
@@ -0,0 +1,24 @@
+diff --git a/dist/index.js b/dist/index.js
+index af8161de27c2c79d0bfdac0edd3e901fcdda7a64..be8e5ef8cd64e4b05d309fddf012c6d74580e4a0 100644
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -3,6 +3,7 @@ export function createFallback(settings) {
+ }
+ const retryableStatusCodes = [
+ 401, // wrong API key
++ 402, // payment required
+ 403, // permission error, like cannot access model or from a non accessible region
+ 408, // request timeout
+ 409, // conflict
+diff --git a/src/index.ts b/src/index.ts
+index aa7b15c825c4c8e19e3eeaaf1b37cf634a627952..9e39400d45c357a53eb3cdf67c63d8a54132fcb6 100644
+--- a/src/index.ts
++++ b/src/index.ts
+@@ -20,6 +20,7 @@ export function createFallback(settings: Settings): FallbackModel {
+
+ const retryableStatusCodes = [
+ 401, // wrong API key
++ 402, // payment required
+ 403, // permission error, like cannot access model or from a non accessible region
+ 408, // request timeout
+ 409, // conflict
diff --git a/bun.lock b/bun.lock
index c4dd01796e..2e5b63ffea 100644
--- a/bun.lock
+++ b/bun.lock
@@ -391,6 +391,7 @@
"patchedDependencies": {
"@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]",
"@tanstack/[email protected]": "apps/web/patches/@tanstack%[email protected]",
+ "[email protected]": "apps/web/patches/[email protected]",
"[email protected]": "apps/web/patches/[email protected]",
"@kobalte/[email protected]": "apps/web/patches/@kobalte%[email protected]",
"[email protected]": "apps/web/patches/[email protected]",
diff --git a/crates/documents/src/outbound/editing_worker_client.rs b/crates/documents/src/outbound/editing_worker_client.rs
index c9922702df..4452c607c6 100644
--- a/crates/documents/src/outbound/editing_worker_client.rs
+++ b/crates/documents/src/outbound/editing_worker_client.rs
@@ -57,8 +57,19 @@ impl EditingWorkerService for ReqwestEditingWorkerClient {
{ "provider": "cerebras", "model": "zai-glm-4.7" },
{ "provider": "anthropic", "model": "claude-sonnet-4-6" },
],
+ // gpt-5.5 leads the coding chain on testbench evidence: replaying
+ // the same 16 prod sessions in the animated (production)
+ // configuration, against the cerebras/haiku chain it cut the
+ // coder retry rate from 37% to 9% (coders retrying 16 -> 2),
+ // runCode calls -63%, input tokens -61%, cost -35%, and judged
+ // quality improved (fully correct 12/16 -> 14/16, purpose met
+ // 14/16 -> 15/16) with no damaging sessions either way.
+ //
+ // haiku stays as the fallback: OpenAI throttles hard under
+ // concurrency, and a throttled bench run at 4-way parallelism
+ // timed out on 24 of 40 cases where a serial run had none.
"coding": [
- { "provider": "cerebras", "model": "gpt-oss-120b" },
+ { "provider": "openai", "model": "gpt-5.5" },
{ "provider": "anthropic", "model": "claude-haiku-4-5" },
],
},
diff --git a/docker/sync-service.Dockerfile b/docker/sync-service.Dockerfile
index 0d450eb6d2..b010e5be85 100644
--- a/docker/sync-service.Dockerfile
+++ b/docker/sync-service.Dockerfile
@@ -1,7 +1,16 @@
# Builder: compiles the worker (Rust -> wasm + JS shim). Nothing from this
# stage's toolchain (rustc, clang, npm dev deps, the cargo target dir) is
# needed at runtime, so it all stays here.
-FROM rust:1.94-bookworm AS builder
+# Pinned to the exact patch the repo's rust-toolchain.toml asks for: the
+# floating 1.94 tag moved to 1.94.1, and rustup then tried to download 1.94.0
+# from scratch on every cargo invocation below.
+FROM rust:1.94.0-bookworm AS builder
+
+# rust-toolchain.toml also names components (rust-src, rust-analyzer) and host
+# targets this image has no use for, which is enough on its own to make rustup
+# re-sync the channel. Selecting the installed toolchain explicitly makes
+# rustup skip the file, so the build never touches static.rust-lang.org.
+ENV RUSTUP_TOOLCHAIN=1.94.0
# Install Node.js 22.x
RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
diff --git a/nix-support/node_modules-hashes.json b/nix-support/node_modules-hashes.json
index a99d455793..4db10355a1 100644
--- a/nix-support/node_modules-hashes.json
+++ b/nix-support/node_modules-hashes.json
@@ -1,6 +1,6 @@
{
"nodeModules": {
- "aarch64-darwin": "sha256-9x1b9zuc0ivnL1QuHPWOSftMsCcfx6L4qYHlMb47ie4=",
- "x86_64-linux": "sha256-rbBTSaprnzGuUZ5iZqtbMRj0cWyfJhL51PXz8NvumAI="
+ "aarch64-darwin": "sha256-62zvY4Lt3mpN9bl42m2T0k9ndedLGUBkWFQlR5qBvXs=",
+ "x86_64-linux": "sha256-MBea1zLaAa/2dTSWmkfDUp/RtWK9SURmMpiGWQ7fKdg="
}
}
diff --git a/package.json b/package.json
index baeccd9d37..6f96f58c5c 100644
--- a/package.json
+++ b/package.json
@@ -40,7 +40,8 @@
"@kobalte/[email protected]": "apps/web/patches/@kobalte%[email protected]",
"[email protected]": "apps/web/patches/[email protected]",
"@tanstack/[email protected]": "apps/web/patches/@tanstack%[email protected]",
- "@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]"
+ "@lexical/[email protected]": "apps/web/patches/@lexical%[email protected]",
+ "[email protected]": "apps/web/patches/[email protected]"
},
"private": true,
"scripts": {
diff --git a/services/ai-editing-worker/src/ai-editing/agents/coder.ts b/services/ai-editing-worker/src/ai-editing/agents/coder.ts
index a558dbc2b8..874a0c4991 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/coder.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/coder.ts
@@ -9,13 +9,25 @@ import {
createRunCodeTool,
} from '../tools';
import { buildPrompt } from './coder-prompt';
-import { EDIT_PROVIDER_OPTIONS } from './model-options';
+import { cachedPrompt, EDIT_PROVIDER_OPTIONS } from './model-options';
import type { RunTaskDeps } from './types';
export type { RunTaskDeps } from './types';
export const CHILD_SYSTEM = `${SHARED}\n${CODER}\n${API_COMPLETE}`;
+/**
+ * Default per-coder step cap.
+ *
+ * Lowering this to 3 was tried and reverted. It did cut runCode calls (139 -> 118
+ * over 40 cases) but the work simply moved up a level: dispatch rounds rose
+ * 79 -> 89 as the supervisor re-dispatched coders it had cut off, cost rose, and
+ * quality fell hard — purpose met 35/40 -> 31/40, fully correct 34/40 -> 28/40.
+ * A coder that needs a fourth step is better served finishing than being
+ * truncated into a fresh dispatch.
+ */
+export const DEFAULT_MAX_CODER_STEPS = 7;
+
/** One writer: carry out a single edit instruction via the `editor` surface. */
export async function coder(
session: LexicalSession,
@@ -26,10 +38,14 @@ export async function coder(
return generateText({
model,
// Stop on the step cap OR the moment the writer declares itself blocked.
- // Cap allows headroom for larger multi-part tasks and a few error retries.
- stopWhen: [stepCountIs(7), hasToolCall('reportBlocked')],
+ stopWhen: [
+ stepCountIs(deps.maxSteps ?? DEFAULT_MAX_CODER_STEPS),
+ hasToolCall('reportBlocked'),
+ ],
system: CHILD_SYSTEM,
- prompt: buildPrompt(task, deps.context, deps.request),
+ // System, tools, and task/context are fixed for this coder's whole run;
+ // one cache breakpoint on the opening message covers all of them.
+ messages: cachedPrompt(buildPrompt(task, deps.context, deps.request)),
tools: {
runCode: createRunCodeTool({
session: session,
@@ -42,7 +58,15 @@ export async function coder(
onOps: deps.onOps,
onRunCode: deps.onRunCode,
span: deps.span,
+ onRunCodeResult: deps.onRunCodeResult,
}),
+ // Always available, even when the coder's window already is the whole
+ // document. Withholding it looked like free savings — the call can only
+ // return what the coder was handed — but the bench says otherwise:
+ // removing it drove coder input tokens +37%, runCode calls 129 -> 168 and
+ // retries 22 -> 28. The re-read is not redundant, it is the coder's only
+ // way to see the document AFTER its own edits, and without that feedback
+ // it makes more blind attempts than the re-read ever cost.
readDocument: createReadDocumentTool({ session }),
reportBlocked: createImBlockedTool(
'Call this instead of guessing when you cannot do the edit -- but only after `readDocument` failed to surface what you need.',
diff --git a/services/ai-editing-worker/src/ai-editing/agents/compact.test.ts b/services/ai-editing-worker/src/ai-editing/agents/compact.test.ts
new file mode 100644
index 0000000000..83fb6acda7
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/agents/compact.test.ts
@@ -0,0 +1,122 @@
+import type { ModelMessage, ToolResultPart } from 'ai';
+import { describe, expect, it } from 'vitest';
+import { compactDocumentHistory } from './compact';
+
+let nextCallId = 0;
+
+function toolMessage(output: ToolResultPart['output']): ModelMessage {
+ return {
+ role: 'tool',
+ content: [
+ {
+ type: 'tool-result',
+ toolCallId: `c${nextCallId++}`,
+ toolName: 'dispatch',
+ output,
+ },
+ ],
+ };
+}
+
+/** A dispatch result: status line, then the post-edit document. */
+const toolResult = (text: string): ModelMessage =>
+ toolMessage({ type: 'text', value: text });
+
+const doc = (body: string) => `✓ APPLIED\n\n<document>\n${body}\n</document>`;
+
+function output(message: ModelMessage): ToolResultPart['output'] {
+ if (message.role !== 'tool') throw new Error('not a tool message');
+ const part = message.content[0];
+ if (part?.type !== 'tool-result') throw new Error('not a tool result');
+ return part.output;
+}
+
+function text(message: ModelMessage): string {
+ const out = output(message);
+ if (out.type !== 'text') throw new Error(`expected text, got ${out.type}`);
+ return out.value;
+}
+
+describe('compactDocumentHistory', () => {
+ it('leaves a single document untouched', () => {
+ const messages = [toolResult(doc('one'))];
+ expect(compactDocumentHistory(messages)).toBe(messages);
+ });
+
+ it('leaves messages with no documents untouched', () => {
+ const messages = [toolResult('ok'), toolResult('ok')];
+ expect(compactDocumentHistory(messages)).toBe(messages);
+ });
+
+ it('elides all but the newest document', () => {
+ const out = compactDocumentHistory([
+ toolResult(doc('FIRST')),
+ toolResult(doc('SECOND')),
+ toolResult(doc('THIRD')),
+ ]);
+
+ expect(text(out[0]!)).not.toContain('FIRST');
+ expect(text(out[0]!)).toContain('omitted');
+ expect(text(out[1]!)).not.toContain('SECOND');
+ // The live state survives verbatim.
+ expect(text(out[2]!)).toContain('<document>');
+ expect(text(out[2]!)).toContain('THIRD');
+ });
+
+ it('keeps the summary that precedes the document', () => {
+ const out = compactDocumentHistory([
+ toolResult(doc('a')),
+ toolResult(doc('b')),
+ ]);
+ expect(text(out[0]!)).toContain('✓ APPLIED');
+ });
+
+ it('ignores non-text outputs', () => {
+ const messages = [
+ toolMessage({ type: 'json', value: { doc: doc('a') } }),
+ toolResult(doc('b')),
+ toolResult(doc('c')),
+ ];
+ const out = compactDocumentHistory(messages);
+ expect(out[0]).toBe(messages[0]);
+ expect(text(out[1]!)).toContain('omitted');
+ });
+
+ it('elides every stale part of a multi-result message', () => {
+ const part = (value: string, id: string): ToolResultPart => ({
+ type: 'tool-result',
+ toolCallId: id,
+ toolName: 'dispatch',
+ output: { type: 'text', value },
+ });
+ const out = compactDocumentHistory([
+ {
+ role: 'tool',
+ content: [part(doc('a'), 'c-a'), part(doc('b'), 'c-b')],
+ },
+ toolResult(doc('c')),
+ ]);
+ const parts = out[0]!.content as ToolResultPart[];
+ for (const p of parts) {
+ expect(p.output.type === 'text' && p.output.value).toContain('omitted');
+ }
+ });
+
+ it('does not mutate the input', () => {
+ const messages = [toolResult(doc('a')), toolResult(doc('b'))];
+ const before = JSON.stringify(messages);
+ compactDocumentHistory(messages);
+ expect(JSON.stringify(messages)).toBe(before);
+ });
+
+ it('is idempotent', () => {
+ const once = compactDocumentHistory([
+ toolResult(doc('a')),
+ toolResult(doc('b')),
+ toolResult(doc('c')),
+ ]);
+ expect(JSON.stringify(compactDocumentHistory(once))).toBe(
+ JSON.stringify(once)
+ );
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/agents/compact.ts b/services/ai-editing-worker/src/ai-editing/agents/compact.ts
new file mode 100644
index 0000000000..8871e997d8
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/agents/compact.ts
@@ -0,0 +1,82 @@
+/**
+ * Drop superseded document snapshots from a supervisor conversation.
+ *
+ * Every `dispatch` result ends with the full post-edit document so the
+ * supervisor can verify the change. That is necessary for the newest result and
+ * pure cost for the rest: once a later dispatch has reported a newer state, the
+ * older copies describe a document that no longer exists, yet they stay in
+ * history and are re-billed on every subsequent step.
+ *
+ * With N dispatches over a D-token document, carrying them all costs O(N²·D)
+ * across the session. Keeping only the newest makes it O(N·D) and — because the
+ * elided text sits after the cached prefix — leaves caching intact.
+ *
+ * The SDK's `pruneMessages` is the wrong tool here: it drops whole tool
+ * call/result pairs, taking each dispatch's `editing_instruction` with them —
+ * and once the document bodies are gone those instructions are the only record
+ * of what each edit was asked to do.
+ */
+
+import type { ModelMessage, ToolContent, ToolResultPart } from 'ai';
+
+const DOC_OPEN = '<document>';
+const DOC_CLOSE = '</document>';
+
+/** A tool result whose output is plain text — the only shape we rewrite. */
+type TextResultPart = ToolResultPart & {
+ output: { type: 'text'; value: string };
+};
+
+function isTextResult(part: ToolContent[number]): part is TextResultPart {
+ return part.type === 'tool-result' && part.output.type === 'text';
+}
+
+/** Replace a result's document block with a one-line marker. */
+function elideDocument(text: string): string | null {
+ const start = text.indexOf(DOC_OPEN);
+ const end = text.indexOf(DOC_CLOSE);
+ if (start === -1 || end === -1 || end < start) return null;
+ const elided = end + DOC_CLOSE.length - start;
+ return `${text.slice(0, start)}[document state after this edit omitted — ${elided} chars; see the latest dispatch result for current content]${text.slice(end + DOC_CLOSE.length)}`;
+}
+
+/**
+ * Return `messages` with every document block elided except the last one.
+ *
+ * Operates on a copy; the caller's array is untouched.
+ */
+export function compactDocumentHistory(
+ messages: ModelMessage[]
+): ModelMessage[] {
+ // Locate every tool-result part that carries a document, in order.
+ const carriers: { messageIndex: number; partIndex: number }[] = [];
+ messages.forEach((message, messageIndex) => {
+ if (message.role !== 'tool') return;
+ message.content.forEach((part, partIndex) => {
+ if (isTextResult(part) && part.output.value.includes(DOC_OPEN)) {
+ carriers.push({ messageIndex, partIndex });
+ }
+ });
+ });
+
+ // Nothing to gain until a newer snapshot has superseded an older one.
+ if (carriers.length < 2) return messages;
+
+ const out = [...messages];
+
+ // Reading each message back out of `out` picks up an earlier rewrite, so a
+ // message holding several parallel dispatch results keeps all of its edits.
+ for (const { messageIndex, partIndex } of carriers.slice(0, -1)) {
+ const message = out[messageIndex];
+ if (message?.role !== 'tool') continue;
+ const part = message.content[partIndex];
+ if (!part || !isTextResult(part)) continue;
+ const elided = elideDocument(part.output.value);
+ if (elided === null) continue;
+ const content = [...message.content];
+ content[partIndex] = { ...part, output: { ...part.output, value: elided } };
+ out[messageIndex] = { ...message, content };
+ }
+
+ return out;
+}
diff --git a/services/ai-editing-worker/src/ai-editing/agents/model-options.ts b/services/ai-editing-worker/src/ai-editing/agents/model-options.ts
index 433ad9ade4..89095d4a62 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/model-options.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/model-options.ts
@@ -1,7 +1,45 @@
import type { AnthropicProviderOptions } from '@ai-sdk/anthropic';
+import type { ModelMessage } from 'ai';
export const EDIT_PROVIDER_OPTIONS = {
anthropic: {
thinking: { type: 'disabled' },
} satisfies AnthropicProviderOptions,
};
+
+/**
+ * The opening user message, marked as a cache breakpoint.
+ *
+ * Anthropic caches the whole prefix up to and including the breakpoint, so one
+ * marker here covers the system prompt, the tool schemas, and the task/document
+ * context — everything that is fixed for the agent's whole run. The breakpoint
+ * goes on the user message rather than a system message so the SDK's
+ * system-in-messages warning doesn't apply.
+ *
+ * Without it Anthropic caches nothing across steps: a 7-step coder was measured
+ * re-billing its ~7.6k-token system prompt every step, 185k input tokens total
+ * for one edit on a 2.5k-token document, with `cachedInputTokens` zero from
+ * step 2 onward.
+ *
+ * Providers that don't understand `anthropic.cacheControl` ignore it, so this
+ * is safe under the cerebras/openai fallbacks.
+ */
+export function cachedPrompt(prompt: string): ModelMessage[] {
+ return [
+ {
+ role: 'user',
+ // The breakpoint must sit on the content PART. Message-level
+ // providerOptions are silently dropped on the way to the provider —
+ // verified against the API, which reported cache_creation_input_tokens 0.
+ content: [
+ {
+ type: 'text',
+ text: prompt,
+ providerOptions: {
+ anthropic: { cacheControl: { type: 'ephemeral' } },
+ },
+ },
+ ],
+ },
+ ];
+}
diff --git a/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts b/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts
index 9ef56e9a73..6e37184f84 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts
@@ -10,8 +10,9 @@ import { TokenTracker } from '../token-tracker';
import { createDispatchTool, createImBlockedTool } from '../tools';
import { numberLines, serializeWithXml } from '../utils';
import { coder } from './coder';
+import { compactDocumentHistory } from './compact';
import { interpreter } from './interpreter';
-import { EDIT_PROVIDER_OPTIONS } from './model-options';
+import { cachedPrompt, EDIT_PROVIDER_OPTIONS } from './model-options';
import type { RunAgentOptions } from './types';
export type { RunAgentOptions } from './types';
@@ -87,6 +88,7 @@ export async function supervisor(
sleep: opts.sleep,
signal: opts.signal,
makeWriter: opts.borrowWriter,
+ maxCoderSteps: opts.maxCoderSteps,
runTask: coder,
serialize,
runner: opts.runner,
@@ -116,11 +118,11 @@ export async function supervisor(
model: models.supervisor,
stopWhen: [stepCountIs(7), hasToolCall('reportBlocked')],
system: MASTER_SYSTEM,
- prompt,
+ messages: cachedPrompt(prompt),
tools,
providerOptions: EDIT_PROVIDER_OPTIONS,
abortSignal: opts.signal,
- prepareStep: ({ stepNumber }) => {
+ prepareStep: ({ stepNumber, messages }) => {
// A step that throws mid-flight never reaches onStepFinish; close any
// straggler so turns stay one-to-one with spans.
endTurn();
@@ -128,7 +130,12 @@ export async function supervisor(
turnSpan.setAttr('turn.index', stepNumber);
turnSpan.setAttr('gen_ai.operation.name', 'chat');
// require that the very first thing it does is a tool call
- return stepNumber === 0 ? { toolChoice: 'required' } : undefined;
+ return {
+ ...(stepNumber === 0 ? { toolChoice: 'required' as const } : {}),
+ // Only the newest dispatch result describes the live document; older
+ // copies are stale and would be re-billed on every remaining step.
+ messages: compactDocumentHistory(messages),
+ };
},
onStepFinish: (step) => {
const now = Date.now();
diff --git a/services/ai-editing-worker/src/ai-editing/agents/types.ts b/services/ai-editing-worker/src/ai-editing/agents/types.ts
index f22219f1cd..5ceaf948a5 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/types.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/types.ts
@@ -12,6 +12,9 @@ import type {
export type RunTaskDeps = {
doc: Doc;
+ /** Max model steps for this coder. `runCode` takes arbitrary JS, so any edit
+ * can be expressed in ONE call; further steps are error recovery. */
+ maxSteps?: number;
awarenessSource: AwarenessSource;
runner: RunCodeToolOptions['runner'];
context: string;
@@ -26,10 +29,13 @@ export type RunTaskDeps = {
onRunCode?: RunCodeToolOptions['onRunCode'];
/** This coder's `edit.dispatch` span; parents its `edit.run_code` children. */
span?: Span;
+ onRunCodeResult?: RunCodeToolOptions['onRunCodeResult'];
};
export type RunAgentOptions = {
borrowWriter: () => Promise<Writer>;
+ /** Overrides the per-coder step cap; see RunTaskDeps.maxSteps. */
+ maxCoderSteps?: number;
docFormat?: 'markdown' | 'xml';
interpret?: boolean;
runner: RunCodeToolOptions['runner'];
diff --git a/services/ai-editing-worker/src/ai-editing/ai-toolkit/inline.ts b/services/ai-editing-worker/src/ai-editing/ai-toolkit/inline.ts
index f476538d10..cb75daa189 100644
--- a/services/ai-editing-worker/src/ai-editing/ai-toolkit/inline.ts
+++ b/services/ai-editing-worker/src/ai-editing/ai-toolkit/inline.ts
@@ -221,14 +221,44 @@ function mutateMatches(
return count;
}
-/** Wrap a matched substring in a new element node (link, mark, …). Returns the count changed. */
+/** How to recognise and update a wrapper that is already in place. */
+export type ExistingWrapper = {
+ /** True for a wrapper of the same kind as `createWrapper` produces. */
+ is: (node: LexicalNode) => boolean;
+ /** Bring the existing wrapper in line with the requested change. */
+ update: (node: ElementNode) => void;
+};
+
+/**
+ * Wrap a matched substring in a new element node (link, mark, …). Returns the
+ * count changed.
+ *
+ * When `existing` is supplied and the match already sits inside a wrapper of
+ * that kind, the existing wrapper is updated instead of a new one being nested
+ * inside it. Without this, `link()` on already-linked text produced
+ *
+ * <a href="https://old.test"><a href="https://new.test">docs</a></a>
+ *
+ * — a malformed nested anchor that also left the stale href in place, and no
+ * API existed to retarget a link at all. Ten defects across the failure corpus
+ * trace back to it.
+ */
export function $wrapInBlock(
block: ElementNode,
needle: string,
createWrapper: () => ElementNode,
- scope?: Scope
+ scope?: Scope,
+ existing?: ExistingWrapper
): number {
return mutateMatches(block, needle, scope, (matchNode) => {
+ if (existing) {
+ const parent = matchNode.getParent();
+ const enclosing = parent ? $findMatchingParent(parent, existing.is) : null;
+ if (enclosing && $isElementNode(enclosing)) {
+ existing.update(enclosing);
+ return;
+ }
+ }
const wrapper = createWrapper();
matchNode.replace(wrapper);
wrapper.append(matchNode);
diff --git a/services/ai-editing-worker/src/ai-editing/doc/concurrency.test.ts b/services/ai-editing-worker/src/ai-editing/doc/concurrency.test.ts
new file mode 100644
index 0000000000..8252a3f89d
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/doc/concurrency.test.ts
@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import { mockAwarenessSource } from '../awareness/awareness-source';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { DocumentEditor } from '../editor/document-editor';
+import { type CodeRunner, runEditorCode } from '../runtime';
+import { serializeWithXml } from '../utils';
+import { Doc } from './doc';
+
+/**
+ * Concurrency reproductions at the scale the failure reports describe.
+ *
+ * An earlier attempt used two writers doing simple inserts and came out clean,
+ * which was too weak to justify dismissing the class. The reports describe FOUR
+ * OR FIVE concurrent dispatches doing `setText` on existing text nodes, and
+ * damage landing on nodes a coder was not targeting:
+ *
+ * 034f576f "eric's cell and peter's cell — which Dispatch 2 was NOT targeting"
+ * 305047cd "at least 4 concurrent coder dispatches ... one coder's write to the
+ * heading node collided with a sibling-node write" (heading emptied)
+ * 15c0d49a "one coder's in-progress streamed write interleaved with another"
+ * (bullet permanently truncated)
+ *
+ * Refs are unique per invocation, as `runInSandbox` guarantees via nanoid — a
+ * shared pool produces collisions that have nothing to do with concurrency.
+ */
+let refSeq = 0;
+const runner: CodeRunner = (validIds, code, snippets) => {
+ const base = ++refSeq;
+ const refs = Array.from({ length: 128 }, (_, i) => `r${base}-${i}`);
+ const editor = new DocumentEditor({ validIds, refs });
+ new Function('editor', 'snippets', code)(editor, snippets ?? {});
+ return editor.drain();
+};
+
+function build(md: string) {
+ const session = createEditingSession();
+ loadMarkdown(session, md);
+ const doc = new Doc(session);
+ return {
+ xml: () => serializeWithXml(session),
+ /** Animated path — what prod runs; the Rust caller never sets typingAnimations. */
+ run: (code: string) =>
+ runEditorCode({
+ session,
+ doc,
+ code,
+ runner,
+ awarenessSource: mockAwarenessSource(),
+ sleep: () => Promise.resolve(),
+ }),
+ };
+}
+
+/** Text-run ids in document order. */
+const textIds = (xml: string) =>
+ [...xml.matchAll(/<t id="([^"]+)"/g)].map((m) => m[1]!);
+
+const textOf = (xml: string) =>
+ [...xml.matchAll(/<t[^>]*>([^<]*)<\/t>/g)].map((m) => m[1]!);
+
+describe('concurrent writers at report scale', () => {
+ it('five writers each setText a different node, all land, none bleed', async () => {
+ const rows = ['alpha', 'bravo', 'charlie', 'delta', 'echo'];
+ const b = build(rows.join('\n\n'));
+ const ids = textIds(b.xml());
+ expect(ids).toHaveLength(5);
+
+ await Promise.all(
+ ids.map((id, i) => b.run(`editor.setText('${id}', 'CHANGED-${i}');`))
+ );
+
+ const out = textOf(b.xml());
+ for (let i = 0; i < 5; i++) expect(out).toContain(`CHANGED-${i}`);
+ // Nothing may be left empty or half-written.
+ expect(out.filter((t) => t === '')).toHaveLength(0);
+ for (const t of out) expect(t).toMatch(/^CHANGED-\d$/);
+ });
+
+ it('four writers appending to different nodes do not truncate each other', async () => {
+ const b = build(['one', 'two', 'three', 'four'].join('\n\n'));
+ const ids = textIds(b.xml());
+ await Promise.all(
+ ids.map((id, i) => b.run(`editor.appendText('${id}', ' [${i}]');`))
+ );
+ const out = textOf(b.xml());
+ expect(out).toEqual(['one [0]', 'two [1]', 'three [2]', 'four [3]']);
+ });
+
+ it('a writer editing one heading does not empty a sibling heading', async () => {
+ const b = build('## first heading\n\n## second heading\n\nbody text');
+ const ids = textIds(b.xml());
+ await Promise.all([
+ b.run(`editor.setText('${ids[0]}', 'FIRST rewritten');`),
+ b.run(`editor.setText('${ids[1]}', 'SECOND rewritten');`),
+ b.run(`editor.appendText('${ids[2]}', ' extended');`),
+ ]);
+ const out = b.xml();
+ expect(out).toContain('FIRST rewritten');
+ expect(out).toContain('SECOND rewritten');
+ // No emptied heading — the 305047cd signature.
+ expect(out).not.toMatch(/<h2 id="[^"]+"\/>/);
+ });
+
+ it('writers editing one row do not damage rows they never named', async () => {
+ const b = build('julia 0\n\neric 0\n\npeter 0');
+ const ids = textIds(b.xml());
+ await Promise.all([
+ b.run(`editor.setText('${ids[0]}', 'julia -1.1');`),
+ b.run(`editor.appendText('${ids[1]}', '');`),
+ ]);
+ const out = textOf(b.xml());
+ expect(out).toContain('julia -1.1');
+ // Rows nobody targeted survive verbatim — the 034f576f signature.
+ expect(out).toContain('eric 0');
+ expect(out).toContain('peter 0');
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/doc/corpus-bugs.test.ts b/services/ai-editing-worker/src/ai-editing/doc/corpus-bugs.test.ts
new file mode 100644
index 0000000000..06dde9fd7e
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/doc/corpus-bugs.test.ts
@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest';
+import { mockAwarenessSource } from '../awareness/awareness-source';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { DocumentEditor } from '../editor/document-editor';
+import { type CodeRunner, docIds, runEditorCode } from '../runtime';
+import { serializeWithXml } from '../utils';
+import { Doc } from './doc';
+
+/**
+ * One `it` per claim taken from the hand-written failure reports, so a claim can
+ * be confirmed or dismissed before anything is changed for it.
+ */
+/** Refs must be globally unique per invocation, as `runInSandbox` guarantees via
+ * nanoid — a shared pool would make two concurrent writers mint the same ref and
+ * collide for reasons that have nothing to do with the code under test. */
+let refSeq = 0;
+const runner: CodeRunner = (validIds, code, snippets) => {
+ const base = ++refSeq;
+ const refs = Array.from({ length: 128 }, (_, i) => `ref-${base}-${i + 1}`);
+ const editor = new DocumentEditor({ validIds, refs });
+ new Function('editor', 'snippets', code)(editor, snippets ?? {});
+ return editor.drain();
+};
+
+function build(md: string) {
+ const session = createEditingSession();
+ loadMarkdown(session, md);
+ const doc = new Doc(session);
+ return {
+ session,
+ doc,
+ xml: () => serializeWithXml(session),
+ ids: () => [...docIds(session)],
+ /** Animated path — what prod runs, since the caller never sets
+ * typingAnimations. */
+ run: (code: string, snippets?: Record<string, string>) =>
+ runEditorCode({
+ session,
+ doc,
+ code,
+ runner,
+ awarenessSource: mockAwarenessSource(),
+ sleep: () => Promise.resolve(),
+ snippets,
+ }),
+ /** Direct-apply path, used when animations are disabled. */
+ runInstant: (code: string) =>
+ runEditorCode({
+ session,
+ doc,
+ code,
+ runner,
+ awarenessSource: mockAwarenessSource(),
+ sleep: () => Promise.resolve(),
+ typingAnimations: false,
+ }),
+ };
+}
+
+const blockIds = (xml: string) =>
+ [...xml.matchAll(/<(?:p|h[1-6]|li) id="([^"]+)"/g)].map((m) => m[1]!);
+
+describe('claims from the failure corpus', () => {
+ // 20fbd0f4: "A concurrent dispatch's insertParagraphAfter for the new
+ // paragraph was lost in the last-write-wins merge."
+ // Verified NOT a product bug: the interleaving originally seen here came from
+ // a shared ref pool in this test file, not from the animation queue. With
+ // unique refs — which `runInSandbox` guarantees via nanoid — concurrent
+ // animated writers do not interleave. Kept as a guard.
+ it('keeps both inserts when two writers append after the same node (animated)', async () => {
+ const b = build('anchor paragraph');
+ const anchor = blockIds(b.xml())[0]!;
+ await Promise.all([
+ b.run(`editor.insertParagraphAfter('${anchor}', 'from writer A');`),
+ b.run(`editor.insertParagraphAfter('${anchor}', 'from writer B');`),
+ ]);
+ const out = b.xml();
+ expect(out).toContain('from writer A');
+ expect(out).toContain('from writer B');
+ // No interleaving: neither insert may appear spliced into the other.
+ expect(out).not.toMatch(/from writer B[^<]*A/);
+ });
+
+ it('keeps both inserts with animations disabled too', async () => {
+ const b = build('anchor paragraph');
+ const anchor = blockIds(b.xml())[0]!;
+ await Promise.all([
+ b.runInstant(`editor.insertParagraphAfter('${anchor}', 'from writer A');`),
+ b.runInstant(`editor.insertParagraphAfter('${anchor}', 'from writer B');`),
+ ]);
+ expect(b.xml()).toContain('from writer A');
+ expect(b.xml()).toContain('from writer B');
+ });
+
+ it('does not interleave two writers typing into the same paragraph', async () => {
+ const b = build('seed');
+ const id = blockIds(b.xml())[0]!;
+ await Promise.all([
+ b.run(`editor.appendText('${id}', 'AAAAAAAA');`),
+ b.run(`editor.appendText('${id}', 'BBBBBBBB');`),
+ ]);
+ const text = b.xml().match(/<t[^>]*>([^<]*)<\/t>/)?.[1] ?? '';
+ // Each run must appear as one contiguous block, in some order.
+ expect(text).toMatch(/^seed(AAAAAAAABBBBBBBB|BBBBBBBBAAAAAAAA)$/);
+ });
+
+ // 20fbd0f4: "one coder's setText/replace on node X was lost" — two writers
+ // editing DIFFERENT sibling nodes concurrently.
+ it('keeps both edits when two writers change different sibling blocks', async () => {
+ const b = build('first block\n\nsecond block');
+ const [one, two] = blockIds(b.xml());
+ await Promise.all([
+ b.run(`editor.setText('${one}', 'ONE changed');`),
+ b.run(`editor.setText('${two}', 'TWO changed');`),
+ ]);
+ const out = b.xml();
+ expect(out).toContain('ONE changed');
+ expect(out).toContain('TWO changed');
+ });
+
+ // 02d942d1: "the coder repeatedly could not reliably un-nest a <li><ul><li>
+ // structure in place; it took a full delete+recreate."
+ it('can flatten a nested list item with outdent', async () => {
+ const b = build('- outer\n - nested item\n');
+ const nested = [...b.xml().matchAll(/<li id="([^"]+)"/g)].map((m) => m[1]!);
+ const inner = nested[nested.length - 1]!;
+ const result = await b.run(`editor.outdent('${inner}');`);
+ expect(result).not.toMatch(/^error/);
+ expect(result).toContain('CHANGED');
+ });
+
+ // 1259cd5a: "written to the document containing literal backslash-quote
+ // characters (e.g. \\"Stop,\\")" — does snippet text leak escapes?
+ it('does not leak backslashes from snippet text', async () => {
+ const b = build('placeholder');
+ const id = blockIds(b.xml())[0]!;
+ await b.run(`editor.setText('${id}', snippets.line);`, {
+ line: 'She said "Stop," and left.',
+ });
+ const out = b.xml();
+ expect(out).toContain('&quot;Stop,&quot;');
+ expect(out).not.toContain('\\');
+ });
+
+ // 02d942d1: "coder called editor.remove with an ID that never appeared in the
+ // trace" — must be rejected, not silently applied elsewhere.
+ it('rejects a fabricated node id with a clear error', async () => {
+ const b = build('untouched content');
+ const before = b.xml();
+ const result = await b.run(`editor.remove('lXTpAA3g');`);
+ expect(result).toMatch(/error/);
+ expect(result).toMatch(/lXTpAA3g/);
+ expect(b.xml()).toBe(before);
+ });
+
+ // d8f37ff1: "editor.link only accepts href and text, so rel/target were
+ // silently omitted" — a capability gap, recorded so it is not forgotten.
+ it('has no surface for rel/target on a link', async () => {
+ const b = build('see docs here');
+ const id = blockIds(b.xml())[0]!;
+ await b.run(`editor.link('${id}', 'docs', 'https://x.test');`);
+ const out = b.xml();
+ expect(out).toContain('href="https://x.test"');
+ // Documents current behaviour: no way to ask for these.
+ expect(out).not.toContain('rel=');
+ expect(out).not.toContain('target=');
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/doc/doc.ts b/services/ai-editing-worker/src/ai-editing/doc/doc.ts
index 6062bc01aa..045505f899 100644
--- a/services/ai-editing-worker/src/ai-editing/doc/doc.ts
+++ b/services/ai-editing-worker/src/ai-editing/doc/doc.ts
@@ -8,7 +8,7 @@
*/
import { $createCodeNode } from '@lexical/code';
-import { $createLinkNode, $isLinkNode } from '@lexical/link';
+import { $createLinkNode, $isLinkNode, type LinkNode } from '@lexical/link';
import {
$createListItemNode,
$createListNode,
@@ -72,6 +72,7 @@ import * as blocks from '../ai-toolkit/blocks';
import * as inline from '../ai-toolkit/inline';
import * as lists from '../ai-toolkit/lists';
import * as locate from '../ai-toolkit/locate';
+import { assertSubstringMatched } from './substring-miss';
import * as modify from '../ai-toolkit/modify';
import type { LexicalSession } from '../ai-toolkit/session';
import * as tables from '../ai-toolkit/tables';
@@ -111,6 +112,19 @@ export class Doc implements DocReader, DocWriter {
return node;
}
+ /** See DocReader.blockRef. Falls back to the input when nothing resolves, so a
+ * planning read can never throw where the apply would report a clean error. */
+ public blockRef(node: NodeRef): NodeRef {
+ try {
+ return this.session.editor.getEditorState().read(() => {
+ const block = locate.$blockById(this.session, node as string);
+ return ($getId(block) as NodeRef | undefined) ?? node;
+ });
+ } catch {
+ return node;
+ }
+ }
+
public apply(op: DocumentOp): void {
match(op)
.with({ kind: 'insertText' }, (e) =>
@@ -285,8 +299,38 @@ export class Doc implements DocReader, DocWriter {
this.tx(() => removeTextAt(this.block(node), at, len));
}
+ /**
+ * Set text content.
+ *
+ * Given a BLOCK id this replaces the block's contents, which is what the name
+ * promises. Given an inline text-run id it sets THAT RUN and leaves its
+ * siblings alone — matching `appendText`, `replace`, `bold` and friends, all of
+ * which already act on the run they are handed.
+ *
+ * Widening a run id to its block was the single largest remaining source of
+ * coder retries. `$setText` keeps only the block's FIRST text child and deletes
+ * the rest, so a coder rewriting several runs in one paragraph destroyed its own
+ * remaining targets with the first call:
+ *
+ * editor.setText('n9qP6lV-', '…') -> ok
+ * editor.setText('eNt8jsxy', 'him') -> error: No node with id "eNt8jsxy"
+ * editor.setText('rYT9Q8LF', '. …') -> error: No node with id "rYT9Q8LF"
+ * CHANGED — removed eNt8jsxy, rYT9Q8LF, IoUm7NTJ, …
+ *
+ * It could even remove the node it was given, when that run was not the first
+ * child. Addressing runs individually is both what the call reads as and the
+ * only way a multi-run rewrite can work.
+ */
private setText(node: NodeRef, text: string): void {
- this.tx(() => blocks.$setText(this.block(node), text));
+ this.tx(() => {
+ const target = locate.$byId(this.session, node as string);
+ if ($isTextNode(target)) {
+ if (text.length === 0) target.remove();
+ else target.setTextContent(text);
+ return;
+ }
+ blocks.$setText(this.block(node), text);
+ });
}
private appendText(node: NodeRef, text: string): void {
@@ -310,13 +354,35 @@ export class Doc implements DocReader, DocWriter {
});
}
+ /** A miss on any substring-targeted op used to apply nothing and report
+ * success. Every one of these now raises instead — see ./substring-miss.ts. */
+ private assertMatched(
+ count: number,
+ block: ElementNode,
+ node: NodeRef,
+ operation: string,
+ needle: string
+ ): void {
+ assertSubstringMatched(
+ count,
+ block,
+ typeof node === 'string' ? node : block.getType(),
+ operation,
+ needle
+ );
+ }
+
private replaceText(
node: NodeRef,
find: string,
to: string,
scope: Scope
): void {
- this.tx(() => inline.$replaceString(this.block(node), find, to, scope));
+ this.tx(() => {
+ const block = this.block(node);
+ const count = inline.$replaceString(block, find, to, scope);
+ this.assertMatched(count, block, node, 'replace', find);
+ });
}
private formatText(
@@ -328,8 +394,10 @@ export class Doc implements DocReader, DocWriter {
): void {
this.tx(() => {
const block = this.block(node);
- if (on) inline.$formatTextInBlock(block, match, format, scope);
- else inline.$clearFormat(block, match, format, scope);
+ const count = on
+ ? inline.$formatTextInBlock(block, match, format, scope)
+ : inline.$clearFormat(block, match, format, scope);
+ this.assertMatched(count, block, node, `${format}`, match);
});
}
@@ -340,8 +408,12 @@ export class Doc implements DocReader, DocWriter {
): void {
this.tx(() => {
const block = this.block(node);
- if (match === undefined) inline.$stripFormat(block);
- else inline.$clearFormat(block, match, undefined, scope);
+ if (match === undefined) {
+ inline.$stripFormat(block);
+ return;
+ }
+ const count = inline.$clearFormat(block, match, undefined, scope);
+ this.assertMatched(count, block, node, 'clearFormat', match);
});
}
@@ -352,9 +424,11 @@ export class Doc implements DocReader, DocWriter {
scope: Scope
): void {
this.tx(() => {
- if (on)
- inline.$wrapInBlock(this.block(node), match, $createMarkNode, scope);
- else inline.$unwrapFromBlock(this.block(node), match, $isMarkNode, scope);
+ const block = this.block(node);
+ const count = on
+ ? inline.$wrapInBlock(block, match, $createMarkNode, scope)
+ : inline.$unwrapFromBlock(block, match, $isMarkNode, scope);
+ this.assertMatched(count, block, node, 'mark', match);
});
}
@@ -365,14 +439,20 @@ export class Doc implements DocReader, DocWriter {
scope: Scope
): void {
this.tx(() => {
- if (url !== null)
- inline.$wrapInBlock(
- this.block(node),
- match,
- () => $createLinkNode(url),
- scope
- );
- else inline.$unwrapFromBlock(this.block(node), match, $isLinkNode, scope);
+ const block = this.block(node);
+ const count =
+ url !== null
+ ? inline.$wrapInBlock(
+ block,
+ match,
+ () => $createLinkNode(url),
+ scope,
+ // Retarget an anchor the text is already inside rather than
+ // nesting a second one within it.
+ { is: $isLinkNode, update: (n) => (n as LinkNode).setURL(url) }
+ )
+ : inline.$unwrapFromBlock(block, match, $isLinkNode, scope);
+ this.assertMatched(count, block, node, 'link', match);
});
}
diff --git a/services/ai-editing-worker/src/ai-editing/doc/interfaces.ts b/services/ai-editing-worker/src/ai-editing/doc/interfaces.ts
index 1736a114d4..2d1b942c64 100644
--- a/services/ai-editing-worker/src/ai-editing/doc/interfaces.ts
+++ b/services/ai-editing-worker/src/ai-editing/doc/interfaces.ts
@@ -17,6 +17,13 @@ export interface DocReader {
textLength(node: NodeRef): number;
/** The content block node of a table cell (header is row 0). */
cellNode(table: NodeId, row: number, col: number): NodeRef;
+ /** The enclosing block for a ref, matching how mutating ops resolve it.
+ *
+ * Animators must plan against the same node `Doc` will mutate. Planning
+ * against an inline text run instead breaks whenever a step empties it:
+ * Lexical drops empty text nodes, so the ref every later step depends on
+ * stops existing mid-animation. */
+ blockRef(node: NodeRef): NodeRef;
}
export interface DocWriter {
diff --git a/services/ai-editing-worker/src/ai-editing/doc/link-bugs.test.ts b/services/ai-editing-worker/src/ai-editing/doc/link-bugs.test.ts
new file mode 100644
index 0000000000..d2bcb617ee
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/doc/link-bugs.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { serializeWithXml } from '../utils';
+import { Doc } from './doc';
+
+/**
+ * Reproductions for the `link` defects the failure reports name. Each `it` is a
+ * claim from a specific trace; the point is to find out which are real before
+ * changing anything.
+ */
+function build(md: string) {
+ const session = createEditingSession();
+ loadMarkdown(session, md);
+ const doc = new Doc(session);
+ const xml = () => serializeWithXml(session);
+ const id = xml().match(/<p id="([^"]+)"/)?.[1]!;
+ return { session, doc, xml, id };
+}
+
+const link = (node: string, match: string, url: string | null) =>
+ ({ kind: 'linkText', node, match, url }) as never;
+
+describe('link defects from the failure corpus', () => {
+ // trace 90f5450c: "the hyperlink swallowed the entire remaining text of the
+ // bullet instead of only '#4863'". Shared engine with bold/inlineCode, so if
+ // real this is much wider than link.
+ it('wraps only the matched substring, not the rest of the block', () => {
+ const { doc, xml, id } = build('see #4863 after being merged');
+ doc.apply(link(id, '#4863', 'https://x.test/4863'));
+ const anchor = xml().match(/<a[^>]*>[\s\S]*?<\/a>/)?.[0] ?? '';
+ expect(anchor).toContain('#4863');
+ expect(anchor).not.toContain('after being merged');
+ });
+
+ it('wraps only the matched substring when the match is at the start', () => {
+ const { doc, xml, id } = build('#4863 trailing words here');
+ doc.apply(link(id, '#4863', 'https://x.test/4863'));
+ const anchor = xml().match(/<a[^>]*>[\s\S]*?<\/a>/)?.[0] ?? '';
+ expect(anchor).not.toContain('trailing words here');
+ });
+
+ // trace 07218654: "editor.link inserted a second, nested <a> inside the
+ // original one ... with the placeholder URL still present".
+ it('does not nest a second anchor inside an existing one', () => {
+ const { doc, xml, id } = build('go to [docs](https://old.test) now');
+ doc.apply(link(id, 'docs', 'https://new.test'));
+ const out = xml();
+ // No <a> directly containing another <a>.
+ expect(out).not.toMatch(/<a[^>]*>[\s\S]*?<a[^>]*>/);
+ });
+
+ it('retargets an existing link rather than leaving the old href', () => {
+ const { doc, xml, id } = build('go to [docs](https://old.test) now');
+ doc.apply(link(id, 'docs', 'https://new.test'));
+ const out = xml();
+ expect(out).toContain('https://new.test');
+ expect(out).not.toContain('https://old.test');
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/doc/settext-scope.test.ts b/services/ai-editing-worker/src/ai-editing/doc/settext-scope.test.ts
new file mode 100644
index 0000000000..d2ceb149c3
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/doc/settext-scope.test.ts
@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { mockAwarenessSource } from '../awareness/awareness-source';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { DocumentEditor } from '../editor/document-editor';
+import { type CodeRunner, runEditorCode } from '../runtime';
+import { serializeWithXml } from '../utils';
+import { Doc } from './doc';
+
+/**
+ * `setText` must act on the node it is handed.
+ *
+ * Widening an inline run id to its enclosing block was the largest remaining
+ * source of coder retries: `$setText` keeps only the block's first text child, so
+ * a coder rewriting several runs in one paragraph destroyed its own remaining
+ * targets with the first call. Observed in trace 050417a1 as a run of
+ * `No node with id "…"` errors immediately after one successful call.
+ */
+let refSeq = 0;
+const runner: CodeRunner = (validIds, code, snippets) => {
+ const base = ++refSeq;
+ const editor = new DocumentEditor({
+ validIds,
+ refs: Array.from({ length: 128 }, (_, i) => `r${base}-${i}`),
+ });
+ new Function('editor', 'snippets', code)(editor, snippets ?? {});
+ return editor.drain();
+};
+
+function build(md: string) {
+ const session = createEditingSession();
+ loadMarkdown(session, md);
+ const doc = new Doc(session);
+ return {
+ xml: () => serializeWithXml(session),
+ run: (code: string) =>
+ runEditorCode({
+ session,
+ doc,
+ code,
+ runner,
+ awarenessSource: mockAwarenessSource(),
+ sleep: () => Promise.resolve(),
+ }),
+ };
+}
+
+const textIds = (xml: string) =>
+ [...xml.matchAll(/<t id="([^"]+)"/g)].map((m) => m[1]!);
+const textOf = (xml: string) =>
+ [...xml.matchAll(/<t[^>]*>([^<]*)<\/t>/g)].map((m) => m[1]!);
+const blockId = (xml: string) => xml.match(/<p id="([^"]+)"/)![1]!;
+
+describe('setText scope', () => {
+ it('rewrites several runs in one paragraph without losing any', async () => {
+ // "plain **bold** more" gives three sibling runs in one paragraph.
+ const b = build('plain **bold** more');
+ const ids = textIds(b.xml());
+ expect(ids).toHaveLength(3);
+
+ const result = await b.run(
+ ids.map((id, i) => `editor.setText('${id}', 'RUN${i}');`).join('\n')
+ );
+
+ expect(result).not.toMatch(/No node with id/);
+ expect(textOf(b.xml())).toEqual(['RUN0', 'RUN1', 'RUN2']);
+ });
+
+ it('leaves sibling runs untouched when setting one run', async () => {
+ const b = build('keep **target** keep2');
+ const ids = textIds(b.xml());
+ await b.run(`editor.setText('${ids[1]}', 'REPLACED');`);
+ expect(textOf(b.xml())).toEqual(['keep ', 'REPLACED', ' keep2']);
+ });
+
+ it('preserves the formatting of the run it sets', async () => {
+ const b = build('plain **bold** more');
+ const ids = textIds(b.xml());
+ await b.run(`editor.setText('${ids[1]}', 'STILL BOLD');`);
+ const xml = b.xml();
+ expect(xml).toMatch(/<t[^>]*bold="true"[^>]*>STILL BOLD<\/t>/);
+ });
+
+ it('still replaces the whole block when given a block id', async () => {
+ const b = build('plain **bold** more');
+ const id = blockId(b.xml());
+ await b.run(`editor.setText('${id}', 'flattened');`);
+ expect(textOf(b.xml())).toEqual(['flattened']);
+ });
+
+ it('removes a run when set to empty text', async () => {
+ const b = build('keep **drop** keep2');
+ const ids = textIds(b.xml());
+ await b.run(`editor.setText('${ids[1]}', '');`);
+ expect(textOf(b.xml())).toEqual(['keep ', ' keep2']);
+ });
+
+ it('reproduces the 050417a1 pattern: rewrite runs then format one', async () => {
+ const b = build('Calling for **him**');
+ const ids = textIds(b.xml());
+ const result = await b.run(
+ `editor.setText('${ids[0]}', 'Reaching for ');\n` +
+ `editor.setText('${ids[1]}', 'him');\n` +
+ `editor.italic('${ids[1]}', 'him');`
+ );
+ expect(result).not.toMatch(/No node with id/);
+ expect(b.xml()).toContain('Reaching for ');
+ expect(b.xml()).toMatch(/italic="true"/);
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/doc/substring-miss.test.ts b/services/ai-editing-worker/src/ai-editing/doc/substring-miss.test.ts
new file mode 100644
index 0000000000..4074a900a3
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/doc/substring-miss.test.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { docIds } from '../runtime';
+import { serializeWithXml } from '../utils';
+import { Doc } from './doc';
+
+function build(md: string) {
+ const session = createEditingSession();
+ loadMarkdown(session, md);
+ return { session, doc: new Doc(session), ids: [...docIds(session)] };
+}
+
+/** First block id in the document. */
+function blockId(md: string) {
+ const b = build(md);
+ const id = serializeWithXml(b.session).match(/<p id="([^"]+)"/)?.[1];
+ return { ...b, id: id! };
+}
+
+describe('substring-targeted ops report a miss', () => {
+ it('replace throws when the text is absent, quoting what is there', () => {
+ const { doc, id } = blockId('the quick brown fox');
+ expect(() =>
+ doc.apply({ kind: 'replaceText', node: id, find: 'purple', to: 'green' } as never)
+ ).toThrow(/does not occur/);
+ expect(() =>
+ doc.apply({ kind: 'replaceText', node: id, find: 'purple', to: 'green' } as never)
+ ).toThrow(/the quick brown fox/);
+ });
+
+ it('replace succeeds and does not throw when the text is present', () => {
+ const { doc, session, id } = blockId('the quick brown fox');
+ doc.apply({ kind: 'replaceText', node: id, find: 'brown', to: 'red' } as never);
+ expect(serializeWithXml(session)).toContain('red');
+ });
+
+ it('bold throws when the substring is absent', () => {
+ const { doc, id } = blockId('alpha beta');
+ expect(() =>
+ doc.apply({ kind: 'formatText', node: id, match: 'gamma', format: 'bold', on: true } as never)
+ ).toThrow(/does not occur/);
+ });
+
+ it('link throws when the substring is absent', () => {
+ const { doc, id } = blockId('see the docs');
+ expect(() =>
+ doc.apply({ kind: 'linkText', node: id, match: 'manual', url: 'https://x.test' } as never)
+ ).toThrow(/does not occur/);
+ });
+
+ /**
+ * The failure that produced the corpus's worst silent thrash (trace 213282e2):
+ * the needle IS in the block, but split across text runs, so the per-run
+ * matchers can never see it. The coder narrowed from a substring all the way
+ * to the node's entire text and got no error at any point.
+ */
+ it('names the split-run cause when the text spans separate runs', () => {
+ const { doc, session, id } = blockId('total 408 done');
+ // Bold one word so the paragraph holds three separate text runs.
+ doc.apply({ kind: 'formatText', node: id, match: '408', format: 'bold', on: true } as never);
+ const runs = serializeWithXml(session).match(/<t /g) ?? [];
+ expect(runs.length).toBeGreaterThan(1);
+
+ // "total 408" now straddles run 1 and run 2.
+ let message = '';
+ try {
+ doc.apply({ kind: 'replaceText', node: id, find: 'total 408', to: 'total 414' } as never);
+ } catch (e) {
+ message = (e as Error).message;
+ }
+ expect(message).toMatch(/SPLIT ACROSS/);
+ // The runs are quoted so the boundary is visible.
+ expect(message).toContain('"total "');
+ // And it points at the way out.
+ expect(message).toMatch(/setText/);
+ });
+
+ it('clearFormat with no match string still strips everything without throwing', () => {
+ const { doc, id } = blockId('alpha beta');
+ doc.apply({ kind: 'formatText', node: id, match: 'alpha', format: 'bold', on: true } as never);
+ expect(() =>
+ doc.apply({ kind: 'clearFormat', node: id, match: undefined } as never)
+ ).not.toThrow();
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/doc/substring-miss.ts b/services/ai-editing-worker/src/ai-editing/doc/substring-miss.ts
new file mode 100644
index 0000000000..1bec95eb00
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/doc/substring-miss.ts
@@ -0,0 +1,71 @@
+/**
+ * Turn a missed substring match into an actionable error.
+ *
+ * `replace`, `bold`, `italic`, `inlineCode`, `link` and friends all locate their
+ * target by substring. Their engines return a match count, every caller
+ * discarded it, and a miss therefore applied nothing and reported success. Those
+ * four methods alone account for ~2,600 calls across the 495-session prod
+ * corpus, and a silent miss is indistinguishable from a completed edit.
+ *
+ * The observed consequence is the coder guessing. One session spent six calls
+ * trying to fix a total in a bold run, narrowing from a substring to the node's
+ * entire text, getting no error each time:
+ *
+ * editor.replace('_UgddKRe', '408', '414.8') -> nothing
+ * editor.replace('_UgddKRe', '/ 408 с НДС', '/ 414.8 с НДС') -> nothing
+ * editor.replace('_UgddKRe', '<the whole sentence>', '...') -> nothing
+ *
+ * The needle straddled a text-node boundary, and the matchers work per text
+ * node. Nothing in the reply could have told the coder that, so it kept trying
+ * different phrasings of a call that could never work.
+ *
+ * The error names the node, the needle, and the block's actual per-text-node
+ * content — which is what makes the boundary visible.
+ */
+
+import type { ElementNode } from 'lexical';
+
+/** How much of the block's text to quote back. Enough to spot the problem
+ * without pasting a whole document into the coder's context. */
+const MAX_QUOTED = 400;
+
+function clip(text: string): string {
+ return text.length <= MAX_QUOTED
+ ? text
+ : `${text.slice(0, MAX_QUOTED)}… (+${text.length - MAX_QUOTED} chars)`;
+}
+
+/**
+ * Throw if `count` is zero, explaining why the needle could not be found.
+ *
+ * Distinguishes the two real causes:
+ * - the text simply isn't there, versus
+ * - the text IS there but split across text nodes, so no single node holds it.
+ */
+export function assertSubstringMatched(
+ count: number,
+ block: ElementNode,
+ label: string,
+ operation: string,
+ needle: string
+): void {
+ if (count > 0) return;
+
+ const full = block.getTextContent();
+ const runs = block.getAllTextNodes().map((tn) => tn.getTextContent());
+
+ if (full.includes(needle)) {
+ throw new Error(
+ `${operation}: "${needle}" appears in "${label}" but is SPLIT ACROSS separate text runs, ` +
+ `so no single run contains it — substring matching works per run. ` +
+ `The runs are: ${runs.map((r) => JSON.stringify(r)).join(' + ')}. ` +
+ `Target a substring that sits inside ONE run, or replace the whole block's text with setText.`
+ );
+ }
+
+ throw new Error(
+ `${operation}: "${needle}" does not occur in "${label}". ` +
+ `Its text is ${JSON.stringify(clip(full))}. ` +
+ `Match a substring that is actually present (mind punctuation, casing and whitespace).`
+ );
+}
diff --git a/services/ai-editing-worker/src/ai-editing/editor/document-editor.ts b/services/ai-editing-worker/src/ai-editing/editor/document-editor.ts
index 1f7737c35d..f9a8e139fd 100644
--- a/services/ai-editing-worker/src/ai-editing/editor/document-editor.ts
+++ b/services/ai-editing-worker/src/ai-editing/editor/document-editor.ts
@@ -31,6 +31,18 @@ export type DocumentEditorOptions = {
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>;
@@ -48,6 +60,17 @@ export class DocumentEditor {
}
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}"`);
}
@@ -654,4 +677,75 @@ export class DocumentEditor {
}
}
+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 };
diff --git a/services/ai-editing-worker/src/ai-editing/editor/sandbox-init.test.ts b/services/ai-editing-worker/src/ai-editing/editor/sandbox-init.test.ts
new file mode 100644
index 0000000000..b110bc762d
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/editor/sandbox-init.test.ts
@@ -0,0 +1,94 @@
+import { getQuickJS } from 'quickjs-emscripten';
+import { describe, expect, it } from 'vitest';
+import type { DocumentOp } from '.';
+import { SANDBOX_CODE } from '../../editor-sandbox-code';
+import { sandboxInit } from './sandbox-init';
+
+/** Runs a snippet through real QuickJS, as production does. `src/sandbox.ts`
+ * imports the emscripten wasm in a way only wrangler's bundler resolves, so the
+ * test loads the engine via the stock loader instead. */
+async function runSnippet(
+ validIds: Set<string>,
+ code: string
+): Promise<DocumentOp[]> {
+ const QuickJS = await getQuickJS();
+ const ctx = QuickJS.newContext();
+ try {
+ const refs = Array.from({ length: 8 }, (_, i) => `ref-${i}`);
+ ctx.unwrapResult(
+ ctx.evalCode(`${SANDBOX_CODE}\n${sandboxInit(validIds, refs, undefined)}`)
+ ).dispose();
+ ctx.unwrapResult(ctx.evalCode(code)).dispose();
+ const out = ctx.unwrapResult(ctx.evalCode('JSON.stringify(editor.drain())'));
+ const json = ctx.dump(out) as string;
+ out.dispose();
+ return JSON.parse(json) as DocumentOp[];
+ } finally {
+ ctx.dispose();
+ }
+}
+
+/**
+ * Writers reach for plausible-but-absent editor methods. Across 622 prod traces
+ * there are 21 such calls over 12 names, split between missing insert variants
+ * (`insertListAfter`, `appendListItemAfter`, `insertEquationAfter`) and attempts
+ * to READ the document from inside the snippet (`getText`, `getNode`,
+ * `getBlock`, `readBlock`, `lastListItem`) — the editor is write-only.
+ *
+ * A bare `editor.getText is not a function` names the mistake but not the way
+ * out, so the next call is another guess.
+ */
+const ids = new Set(['n1']);
+
+async function failureFor(code: string): Promise<string> {
+ try {
+ await runSnippet(ids, code);
+ return '<no error>';
+ } catch (e) {
+ return e instanceof Error ? e.message : String(e);
+ }
+}
+
+describe('unknown editor methods', () => {
+ it('still runs a real method', async () => {
+ const ops = await runSnippet(ids, `editor.setText('n1', 'x');`);
+ expect(ops).toEqual([{ kind: 'setText', node: 'n1', text: 'x' }]);
+ });
+
+ it('says the method does not exist', async () => {
+ expect(await failureFor(`editor.getText('n1');`)).toMatch(
+ /editor\.getText does not exist/
+ );
+ });
+
+ it('suggests the closest real method', async () => {
+ const msg = await failureFor(`editor.appendListItemAfter('n1', 'x');`);
+ expect(msg).toMatch(/Did you mean/);
+ expect(msg).toMatch(/appendListItem/);
+ });
+
+ it('suggests insert variants for a missing one', async () => {
+ const msg = await failureFor(`editor.insertListAfter('n1', 'x');`);
+ expect(msg).toMatch(/Did you mean/);
+ });
+
+ it('points read attempts at the readDocument tool', async () => {
+ expect(await failureFor(`editor.getBlock('n1');`)).toMatch(
+ /write-only.*readDocument/s
+ );
+ });
+
+ it('keeps real methods bound so chaining still works', async () => {
+ const ops = await runSnippet(
+ ids,
+ `editor.setText('n1', 'a'); editor.bold('n1', 'a');`
+ );
+ expect(ops).toHaveLength(2);
+ });
+
+ it('does not intercept ordinary property reads', async () => {
+ // `drain` is called by the host after the snippet; the proxy must not break it.
+ const ops = await runSnippet(ids, `editor.setText('n1', 'ok');`);
+ expect(Array.isArray(ops)).toBe(true);
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/editor/sandbox-init.ts b/services/ai-editing-worker/src/ai-editing/editor/sandbox-init.ts
new file mode 100644
index 0000000000..d2c6e6cae8
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/editor/sandbox-init.ts
@@ -0,0 +1,22 @@
+/**
+ * The snippet that bootstraps a sandbox before the writer's code runs.
+ *
+ * Shared by every sandbox host so they cannot drift: `src/sandbox.ts` under
+ * wrangler, and any other loader that needs the same context (a replay harness
+ * is only meaningful while it executes what production executes).
+ *
+ * The editor implementation and its unknown-method diagnostics are compiled
+ * into `SANDBOX_CODE`; this function only serializes per-run data.
+ */
+
+/** Build the init source for a sandbox context. */
+export function sandboxInit(
+ validIds: Iterable<string>,
+ refs: string[],
+ snippets: Record<string, string> | undefined
+): string {
+ return [
+ `const editor = createDocumentEditor({ validIds: ${JSON.stringify([...validIds])}, refs: ${JSON.stringify(refs)} });`,
+ `const snippets = ${JSON.stringify(snippets ?? {})};`,
+ ].join('\n');
+}
diff --git a/services/ai-editing-worker/src/ai-editing/effect-report.test.ts b/services/ai-editing-worker/src/ai-editing/effect-report.test.ts
new file mode 100644
index 0000000000..a3781da33e
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/effect-report.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { describeEffect, diffNodes, snapshotNodes } from './effect-report';
+
+const doc = (...lines: string[]) => ['<doc>', ...lines, '</doc>'].join('\n');
+
+describe('snapshotNodes', () => {
+ it('indexes nodes by durable id', () => {
+ const snap = snapshotNodes(
+ doc(' <p id="p1">', ' <t id="t1">hi</t>', ' </p>')
+ );
+ expect([...snap.keys()].sort()).toEqual(['p1', 't1']);
+ });
+
+ it("includes a node's descendants in its body", () => {
+ const snap = snapshotNodes(
+ doc(' <p id="p1">', ' <t id="t1">hi</t>', ' </p>')
+ );
+ expect(snap.get('p1')).toContain('hi');
+ });
+
+ it('ignores nodes without ids', () => {
+ expect([...snapshotNodes(doc(' <br/>')).keys()]).toEqual([]);
+ });
+});
+
+describe('diffNodes', () => {
+ const base = snapshotNodes(
+ doc(' <p id="p1">', ' <t id="t1">before</t>', ' </p>')
+ );
+
+ it('reports no change for an identical document', () => {
+ const effect = diffNodes(base, snapshotNodes(
+ doc(' <p id="p1">', ' <t id="t1">before</t>', ' </p>')
+ ));
+ expect(effect.changed).toBe(false);
+ });
+
+ it('reports a modified node', () => {
+ const effect = diffNodes(base, snapshotNodes(
+ doc(' <p id="p1">', ' <t id="t1">after</t>', ' </p>')
+ ));
+ expect(effect.changed).toBe(true);
+ expect(effect.modifiedIds).toContain('t1');
+ });
+
+ it('reports added and removed nodes', () => {
+ const effect = diffNodes(base, snapshotNodes(
+ doc(' <p id="p2">', ' <t id="t2">new</t>', ' </p>')
+ ));
+ expect(effect.addedIds.sort()).toEqual(['p2', 't2']);
+ expect(effect.removedIds.sort()).toEqual(['p1', 't1']);
+ });
+
+ it('marks a parent modified when a descendant changes', () => {
+ const effect = diffNodes(base, snapshotNodes(
+ doc(' <p id="p1">', ' <t id="t1">after</t>', ' </p>')
+ ));
+ expect(effect.modifiedIds).toContain('p1');
+ });
+});
+
+describe('describeEffect', () => {
+ it('states NO CHANGE as an observable fact, without instructing the model', () => {
+ const out = describeEffect('ok', {
+ changed: false,
+ addedIds: [],
+ removedIds: [],
+ modifiedIds: [],
+ });
+ expect(out).toContain('NO CHANGE');
+ expect(out).toContain('byte-identical');
+ // The exhortation was measured ineffective (8/9 NO CHANGE replies retried
+ // anyway); the raised errors carry the behaviour instead.
+ expect(out).not.toMatch(/Do NOT/i);
+ });
+
+ it('lists what changed so the coder can confirm its target', () => {
+ const out = describeEffect('ok', {
+ changed: true,
+ addedIds: ['n2'],
+ removedIds: ['n3'],
+ modifiedIds: ['n1'],
+ });
+ expect(out).toContain('CHANGED');
+ expect(out).toContain('modified n1');
+ expect(out).toContain('added n2');
+ expect(out).toContain('removed n3');
+ });
+
+ it('keeps a partial failure visible alongside the effect', () => {
+ const out = describeEffect('error: setText: no node "zz"', {
+ changed: true,
+ addedIds: [],
+ removedIds: [],
+ modifiedIds: ['n1'],
+ });
+ expect(out).toContain('error: setText');
+ expect(out).toContain('modified n1');
+ });
+
+ it('caps the id list rather than dumping a whole document', () => {
+ const many = Array.from({ length: 30 }, (_, i) => `n${i}`);
+ const out = describeEffect('ok', {
+ changed: true,
+ addedIds: [],
+ removedIds: [],
+ modifiedIds: many,
+ });
+ expect(out).toContain('+22 more');
+ });
+
+ /**
+ * Regression for the corpus's worst observed thrash (trace dd3c373b): three
+ * check-list items were ALREADY unchecked, so six consecutive `uncheck` /
+ * `setChecked` calls each returned bare `ok` and the coder kept guessing.
+ * The point of this test is that such a call is now self-evidently futile.
+ */
+ it('makes an already-satisfied edit self-evidently futile', () => {
+ const before = snapshotNodes(doc(' <li id="a">', ' <t id="t">x</t>', ' </li>'));
+ const after = snapshotNodes(doc(' <li id="a">', ' <t id="t">x</t>', ' </li>'));
+ const out = describeEffect('ok', diffNodes(before, after));
+ expect(out).toContain('NO CHANGE');
+ expect(out).not.toMatch(/^ok$/);
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/effect-report.ts b/services/ai-editing-worker/src/ai-editing/effect-report.ts
new file mode 100644
index 0000000000..ec9a7b3667
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/effect-report.ts
@@ -0,0 +1,120 @@
+/**
+ * Tell the coder what its code actually did to the document.
+ *
+ * `runCode` used to answer with the bare string `ok` whenever no op threw. That
+ * is ambiguous in the one way that matters: it cannot distinguish
+ *
+ * - the op changed the document,
+ * - the op ran but changed nothing (already in that state, or a no-op), and
+ * - the op ran against the wrong node.
+ *
+ * The coder's only recourse was to try again — with the same call, or with a
+ * different method name it hoped would work. Measured over 495 prod sessions,
+ * 37% of consecutive `runCode` transitions re-touch a node the previous call
+ * already touched: `insertParagraphAfter` repeated verbatim 24 times, `remove`
+ * 18, `setText` 14, and swaps like `appendText`↔`setText` (9) or
+ * `replace`↔`setText` (8). One session spent six calls oscillating between
+ * `uncheck` and `setChecked` on three list items that were *already unchecked*,
+ * getting `ok` every time.
+ *
+ * Reporting the observed effect states plainly which of those happened. On its
+ * own that is not enough — measured over a self-correction sweep, 8 of 9
+ * `NO CHANGE` replies were still followed by a retry, so the ops themselves must
+ * fail loudly (see doc/substring-miss.ts). This exists to make the state
+ * observable, not to instruct the model.
+ */
+
+/** Per-node snapshot of a document, keyed by durable id. */
+export type NodeSnapshot = Map<string, string>;
+
+/** Line-per-node index of the XML view, keyed by `id="..."`.
+ *
+ * A node's "content" is its own line plus every line until the next line at or
+ * above its indentation — cheap, and enough to notice that a node changed. */
+export function snapshotNodes(xml: string): NodeSnapshot {
+ const out: NodeSnapshot = new Map();
+ const lines = xml.split('\n');
+ const indentOf = (line: string) => line.length - line.trimStart().length;
+
+ for (let i = 0; i < lines.length; i++) {
+ const line = lines[i]!;
+ const id = line.match(/\bid="([^"]+)"/)?.[1];
+ if (!id) continue;
+ const indent = indentOf(line);
+ const body: string[] = [line.trim()];
+ for (let j = i + 1; j < lines.length; j++) {
+ const next = lines[j]!;
+ if (next.trim() === '') continue;
+ if (indentOf(next) <= indent) break;
+ body.push(next.trim());
+ }
+ out.set(id, body.join('\n'));
+ }
+ return out;
+}
+
+export type DocumentEffect = {
+ changed: boolean;
+ addedIds: string[];
+ removedIds: string[];
+ modifiedIds: string[];
+};
+
+export function diffNodes(
+ before: NodeSnapshot,
+ after: NodeSnapshot
+): DocumentEffect {
+ const addedIds: string[] = [];
+ const removedIds: string[] = [];
+ const modifiedIds: string[] = [];
+
+ for (const [id, body] of after) {
+ const prev = before.get(id);
+ if (prev === undefined) addedIds.push(id);
+ else if (prev !== body) modifiedIds.push(id);
+ }
+ for (const id of before.keys()) {
+ if (!after.has(id)) removedIds.push(id);
+ }
+
+ return {
+ changed:
+ addedIds.length > 0 || removedIds.length > 0 || modifiedIds.length > 0,
+ addedIds,
+ removedIds,
+ modifiedIds,
+ };
+}
+
+/** Cap the ids listed per bucket — the point is orientation, not an inventory. */
+const MAX_IDS = 8;
+
+function list(label: string, ids: string[]): string | null {
+ if (ids.length === 0) return null;
+ const shown = ids.slice(0, MAX_IDS).join(', ');
+ const rest = ids.length > MAX_IDS ? ` (+${ids.length - MAX_IDS} more)` : '';
+ return `${label} ${shown}${rest}`;
+}
+
+/**
+ * Render the effect for the model.
+ *
+ * `outcome` is whatever the op runner reported (`ok`, or per-op errors). The
+ * effect is appended so a partial failure still says which nodes moved.
+ */
+export function describeEffect(
+ outcome: string,
+ effect: DocumentEffect
+): string {
+ if (!effect.changed) {
+ return `${outcome}\n\nNO CHANGE: the document is byte-identical to before this call.`;
+ }
+
+ const parts = [
+ list('modified', effect.modifiedIds),
+ list('added', effect.addedIds),
+ list('removed', effect.removedIds),
+ ].filter((p): p is string => p !== null);
+
+ return `${outcome}\n\nCHANGED — ${parts.join('; ')}`;
+}
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md b/services/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md
index 4983ee226a..499a4421ae 100644
--- a/services/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md
+++ b/services/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md
@@ -80,8 +80,8 @@ After:
## Text Content
-- `setText(id, text)`
-- `replace(id, find, to, scope?)`
+- `setText(id, text)` — replaces the block's whole contents with one plain run, deleting any bold/code spans, links, mentions and line breaks it contained. Use it to rewrite a block from scratch.
+- `replace(id, find, to, scope?)` — rewrites matching text in place, leaving the rest of the block intact. Use it to edit existing prose. `find` must sit within a single text run.
- `appendText(id, text)` · `prependText(id, text)`
- `setEquation(id, tex)`
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/CODER.md b/services/ai-editing-worker/src/ai-editing/prompts/CODER.md
index fc5e551f6c..c22a6fbe50 100644
--- a/services/ai-editing-worker/src/ai-editing/prompts/CODER.md
+++ b/services/ai-editing-worker/src/ai-editing/prompts/CODER.md
@@ -37,6 +37,8 @@ editor.bold('b5', 'Bluejay');
- **`setText(id, text)` fully replaces a node's content and clears all inline formatting** -- use it whenever you want to overwrite a text node entirely with plain text. `replace(id, find, to)` is only for partial substitutions where `find` is a known substring and you want to preserve surrounding formatting. **For a code block, always rewrite its whole body with `setText` -- never use `replace` on a code block.**
- **All text content goes in the `snippets` argument of your runCode call** -- `runCode({ code: "editor.setText('b3', snippets.intro)", snippets: { intro: "Your composed text." } })` -- referenced as `snippets.KEY` in the code. NEVER embed prose as a string literal inside `code`, so that quotes and apostrophes don't break the code. Use snippets. **Snippet values are raw plain text, so do not escape anything inside them.** Write a literal `"` for a quote, never `\"`; a literal `'` for an apostrophe, never `\'`. Backslash-escaping a snippet value inserts a literal backslash into the document.
- If a call references an id that doesn't exist, you get an error back naming it -- re-read the regions shown, pick the right id, and try again. Don't repeat a failing call.
+- Do the whole task in ONE `runCode` call. The snippet is arbitrary JavaScript, so any number of `editor.*` calls belong in the same call — splitting them across calls costs a round trip and buys nothing. Additional calls are for recovering from an error.
+- Every `runCode` reply states the observed effect: `CHANGED -- modified/added/removed <ids>`, or `NO CHANGE` if the document is byte-identical afterwards. Check the ids are the ones you meant.
- If the instruction refers to a node you **cannot see** in your window, do NOT guess or invent an id. First call `readDocument` to view the whole document and locate the real id. Only if it is genuinely absent should you call `reportBlocked({ message })` to hand the problem back to the supervisor -- that ends your task, so don't also call `runCode`.
- You may use ordinary JS (loops, arrays) to drive many calls. You have the full power of plain JavaScript at your disposal.
- It is **not** your job to try to reason about *why* we are editing the document.
diff --git a/services/ai-editing-worker/src/ai-editing/queue/animators.test.ts b/services/ai-editing-worker/src/ai-editing/queue/animators.test.ts
index 7613f0cc18..461cdd8e1f 100644
--- a/services/ai-editing-worker/src/ai-editing/queue/animators.test.ts
+++ b/services/ai-editing-worker/src/ai-editing/queue/animators.test.ts
@@ -11,6 +11,7 @@ function reader(over: Partial<DocReader> = {}): DocReader {
locate: () => [],
textLength: () => 0,
cellNode: () => 'cell',
+ blockRef: (node: string) => node,
...over,
};
}
diff --git a/services/ai-editing-worker/src/ai-editing/queue/animators.ts b/services/ai-editing-worker/src/ai-editing/queue/animators.ts
index bfe3875403..1d1844da73 100644
--- a/services/ai-editing-worker/src/ai-editing/queue/animators.ts
+++ b/services/ai-editing-worker/src/ai-editing/queue/animators.ts
@@ -145,24 +145,51 @@ function sweepEachThen(
return steps;
}
-/* Replace a node's text by selecting all, deleting, and typing the new content.*/
+/* Replace a node's text by selecting all, deleting, and typing the new content.
+ *
+ * Branches on what the ref points at, because the two cases have incompatible
+ * safety requirements:
+ *
+ * - A BLOCK can be emptied and retyped: it survives having no children, so the
+ * delete-then-type animation is safe and reads well.
+ * - An INLINE RUN cannot. Emptying it makes Lexical drop the node, so every later
+ * step targets an id that no longer exists — the paragraph ends up empty and
+ * the reply claims the id was never there. It is also wrong to widen the ref to
+ * its block, because `setText` on a run means "set this run" and widening
+ * deletes the run's siblings, which is how a coder rewriting several runs in one
+ * paragraph destroyed its own remaining targets.
+ *
+ * So a run is selected and set atomically. That trades character-by-character
+ * typing for correctness on this one path; the block path, which is what a
+ * whole-paragraph rewrite uses, keeps the full animation. */
function retype(
node: NodeRef,
text: string,
ctx: AnimatorCtx
): DocumentOpStep[] {
- const len = ctx.docReader.textLength(node);
- const steps: DocumentOpStep[] = [...selectAll(node, ctx)];
+ const block = ctx.docReader.blockRef(node);
+ const isInlineRun = block !== node;
+
+ if (isInlineRun) {
+ return [
+ ...selectAll(node, ctx),
+ { kind: 'pause', ms: ctx.randomSource.integer(ctx.ranges.settlePauseMs) },
+ edit({ kind: 'setText', node, text }),
+ ];
+ }
+
+ const len = ctx.docReader.textLength(block);
+ const steps: DocumentOpStep[] = [...selectAll(block, ctx)];
if (len > 0) {
steps.push({
kind: 'pause',
ms: ctx.randomSource.integer(ctx.ranges.preDeletePauseMs),
});
- steps.push(edit({ kind: 'removeText', node, at: 0, len }));
- steps.push(cursor(node, 0));
+ steps.push(edit({ kind: 'removeText', node: block, at: 0, len }));
+ steps.push(cursor(block, 0));
}
- steps.push(...typeText(node, text, 0, ctx));
- steps.push(edit({ kind: 'setText', node, text }));
+ steps.push(...typeText(block, text, 0, ctx));
+ steps.push(edit({ kind: 'setText', node: block, text }));
return steps;
}
diff --git a/services/ai-editing-worker/src/ai-editing/queue/cascade.test.ts b/services/ai-editing-worker/src/ai-editing/queue/cascade.test.ts
new file mode 100644
index 0000000000..13b4174d17
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/queue/cascade.test.ts
@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { DocumentEditor } from '../editor/document-editor';
+import { type OpResult, summarize } from './runner';
+
+/**
+ * A failed op leaves its ref dangling, so every dependent op fails too. Those
+ * knock-on failures used to be reported as peers of the real one, producing a
+ * wall of `No node with id "<nanoid>"` lines with nothing to indicate which
+ * failure to act on. Unknown-id errors are the single largest remaining trigger
+ * for a coder retry on the current corpus runs.
+ */
+const ok = (kind: string, node: string): OpResult =>
+ ({ ok: true, op: { kind, node } }) as unknown as OpResult;
+const bad = (kind: string, node: string, error: string): OpResult =>
+ ({ ok: false, op: { kind, node }, error }) as unknown as OpResult;
+
+describe('summarize', () => {
+ it('reports ok when nothing failed', () => {
+ expect(summarize([ok('setText', 'a')])).toBe('ok');
+ });
+
+ it('reports a single independent failure verbatim', () => {
+ const out = summarize([bad('setText', 'a', 'No node with id "a"')]);
+ expect(out).toBe('error: setText: No node with id "a"');
+ expect(out).not.toMatch(/consequence/);
+ });
+
+ it('reports independent failures as peers', () => {
+ const out = summarize([
+ bad('setText', 'a', 'boom'),
+ bad('setText', 'b', 'bang'),
+ ]);
+ expect(out).toContain('error: setText: boom');
+ expect(out).toContain('error: setText: bang');
+ expect(out).not.toMatch(/consequence/);
+ });
+
+ it('collapses failures that depend on an already-failed op', () => {
+ const out = summarize([
+ bad('insertParagraphAfter', 'ref-1', 'target missing'),
+ bad('setText', 'ref-1', 'No node with id "ref-1"'),
+ bad('bold', 'ref-1', 'No node with id "ref-1"'),
+ ]);
+ // The root cause is stated once...
+ expect(out).toContain('error: insertParagraphAfter: target missing');
+ // ...and the knock-on failures are summarised, not repeated.
+ expect(out).not.toContain('No node with id "ref-1"');
+ expect(out).toMatch(/2 later ops referenced a node/);
+ expect(out).toMatch(/Fix the first error/);
+ });
+
+ it('uses singular wording for one consequence', () => {
+ const out = summarize([
+ bad('insertParagraphAfter', 'ref-1', 'target missing'),
+ bad('setText', 'ref-1', 'gone'),
+ ]);
+ expect(out).toMatch(/1 later op referenced/);
+ });
+
+ it('keeps a genuinely unrelated failure visible alongside a cascade', () => {
+ const out = summarize([
+ bad('insertParagraphAfter', 'ref-1', 'target missing'),
+ bad('setText', 'ref-1', 'gone'),
+ bad('setCell', 'table-9', 'not a table'),
+ ]);
+ expect(out).toContain('error: setCell: not a table');
+ expect(out).toMatch(/later op referenced/);
+ });
+});
+
+describe('id argument validation', () => {
+ const editor = () =>
+ new DocumentEditor({ validIds: new Set(['real']), refs: ['ref-1'] });
+
+ it('accepts a known id', () => {
+ expect(() => editor().setText('real', 'x')).not.toThrow();
+ });
+
+ it('names the type when handed an object instead of an id', () => {
+ // `unknown id "[object Object]"` told the writer nothing about what it passed.
+ expect(() =>
+ editor().setText({ id: 'real' } as unknown as string, 'x')
+ ).toThrow(/expected a node id string but got an object with keys \[id\]/);
+ });
+
+ it('names the type when handed an array', () => {
+ expect(() =>
+ editor().setText(['real'] as unknown as string, 'x')
+ ).toThrow(/an array of 1/);
+ });
+
+ it('rejects undefined with a readable message', () => {
+ expect(() => editor().setText(undefined as unknown as string, 'x')).toThrow(
+ /expected a node id string but got undefined/
+ );
+ });
+
+ it('rejects an empty id', () => {
+ expect(() => editor().setText('', 'x')).toThrow(/empty string/);
+ });
+
+ it('still reports a plain unknown id plainly', () => {
+ expect(() => editor().setText('nope', 'x')).toThrow(/unknown id "nope"/);
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/queue/runner.test.ts b/services/ai-editing-worker/src/ai-editing/queue/runner.test.ts
index ed7d8a96a3..b7613d1992 100644
--- a/services/ai-editing-worker/src/ai-editing/queue/runner.test.ts
+++ b/services/ai-editing-worker/src/ai-editing/queue/runner.test.ts
@@ -11,6 +11,7 @@ const reader = (over: Partial<DocReader> = {}): DocReader => ({
locate: () => [{ node: 't1', start: 0, end: 3 }],
textLength: () => 4,
cellNode: () => 'cell',
+ blockRef: (node: string) => node,
...over,
});
diff --git a/services/ai-editing-worker/src/ai-editing/queue/runner.ts b/services/ai-editing-worker/src/ai-editing/queue/runner.ts
index 928b0cdf60..7e8f535e91 100644
--- a/services/ai-editing-worker/src/ai-editing/queue/runner.ts
+++ b/services/ai-editing-worker/src/ai-editing/queue/runner.ts
@@ -73,11 +73,71 @@ function toMessage(e: unknown): string {
throw e;
}
-/** Render only failures; successful ops intentionally produce no detail. */
+/** Op fields that carry node ids. Content fields (`text`, `find`, `kind`, …) must
+ * be excluded or unrelated ops look dependent on each other. */
+const ID_FIELDS = [
+ 'node',
+ 'nodes',
+ 'ref',
+ 'refs',
+ 'table',
+ 'before',
+ 'after',
+] as const;
+
+/** Every node id an op refers to, for detecting knock-on failures. */
+function referencedIds(op: DocumentOp): string[] {
+ const record = op as unknown as Record<string, unknown>;
+ const out: string[] = [];
+ for (const field of ID_FIELDS) {
+ const value = record[field];
+ if (typeof value === 'string') out.push(value);
+ else if (Array.isArray(value)) {
+ for (const v of value) if (typeof v === 'string') out.push(v);
+ }
+ }
+ return out;
+}
+
+/**
+ * Render only failures; successful ops intentionally produce no detail.
+ *
+ * Failures caused by an EARLIER failure are reported as consequences rather than
+ * as peers. One bad op used to produce a wall of equally-weighted errors — a
+ * failed insert left its ref dangling, so every dependent op reported
+ * `No node with id "<nanoid>"` and the writer could not tell which failure was
+ * the real one. Measured on the current corpus runs, unknown-id errors are the
+ * single largest remaining trigger for a retry, and most of those ids are refs
+ * from an op that had already failed.
+ */
export function summarize(results: OpResult[]): string {
const failures = results.filter(
(r): r is Extract<OpResult, { ok: false }> => !r.ok
);
if (failures.length === 0) return 'ok';
- return failures.map((r) => `error: ${r.op.kind}: ${r.error}`).join('\n');
+
+ // Ids that no longer resolve because the op meant to create them failed.
+ const poisoned = new Set<string>();
+ const lines: string[] = [];
+ let consequences = 0;
+
+ for (const result of results) {
+ if (result.ok) continue;
+ const failed = result as Extract<OpResult, { ok: false }>;
+ const dependsOnFailed = referencedIds(result.op).some((id) =>
+ poisoned.has(id)
+ );
+ if (dependsOnFailed) consequences++;
+ else lines.push(`error: ${failed.op.kind}: ${failed.error}`);
+ // Whatever this op would have produced is now unusable downstream.
+ for (const id of referencedIds(result.op)) poisoned.add(id);
+ }
+
+ if (consequences > 0) {
+ lines.push(
+ `${consequences} later op${consequences > 1 ? 's' : ''} referenced a node the failed op above would have created, and could not run. ` +
+ 'Fix the first error; the rest are consequences of it.'
+ );
+ }
+ return lines.join('\n');
}
diff --git a/services/ai-editing-worker/src/ai-editing/runtime.test.ts b/services/ai-editing-worker/src/ai-editing/runtime.test.ts
index e0ddc221fe..d19f84834f 100644
--- a/services/ai-editing-worker/src/ai-editing/runtime.test.ts
+++ b/services/ai-editing-worker/src/ai-editing/runtime.test.ts
@@ -67,7 +67,7 @@ describe('runtime — end to end against real Lexical', () => {
session,
`editor.convertToHeading('${headingId}', 2); editor.bold('${paragraphId}', 'Bluejay');`
);
- expect(summary).toBe('ok');
+ expect(summary).toContain('CHANGED');
const out = serializeWithXml(session);
expect(out).toContain('<h2');
expect(out).toContain('Notes');
@@ -80,7 +80,7 @@ describe('runtime — end to end against real Lexical', () => {
session,
`const p = editor.insertParagraphAfter('${ids[0]}', 'hello'); editor.bold(p, 'hello');`
);
- expect(summary).toBe('ok');
+ expect(summary).toContain('CHANGED');
expect(serializeWithXml(session)).toContain('hello');
});
@@ -118,7 +118,7 @@ describe('runtime — writer-authored snippets', () => {
`editor.insertParagraphAfter('${ids[0]}', snippets.intro);`,
{ intro: 'writer wrote this' }
);
- expect(summary).toBe('ok');
+ expect(summary).toContain('CHANGED');
expect(serializeWithXml(session)).toContain('writer wrote this');
});
diff --git a/services/ai-editing-worker/src/ai-editing/runtime.ts b/services/ai-editing-worker/src/ai-editing/runtime.ts
index 56ba648437..698e4b34a9 100644
--- a/services/ai-editing-worker/src/ai-editing/runtime.ts
+++ b/services/ai-editing-worker/src/ai-editing/runtime.ts
@@ -5,6 +5,7 @@ import type { LexicalSession } from './ai-toolkit/session';
import type { AwarenessSource } from './awareness';
import type { Doc } from './doc';
import type { DocumentOp } from './editor';
+import { describeEffect, diffNodes, snapshotNodes } from './effect-report';
import {
type DocumentOpQueueParams,
type OpResult,
@@ -12,6 +13,7 @@ import {
runQueue,
summarize,
} from './queue';
+import { serializeWithXml } from './utils';
/** Every durable id currently in the document (what the model is allowed to reference). */
export function docIds(session: LexicalSession): Set<string> {
@@ -102,7 +104,12 @@ export async function runEditorCode(args: RunEditorCodeArgs): Promise<string> {
args.onOps?.(ops);
span?.setAttr('ops.count', ops.length);
span?.setAttr('animated', args.typingAnimations !== false);
- if (ops.length === 0) return 'ok';
+ if (ops.length === 0) {
+ return 'ok — but your code produced no editor operations at all. Check that you called `editor.*` methods.';
+ }
+
+ // Snapshot before applying so the coder can be told what actually moved.
+ const before = snapshotNodes(serializeWithXml(args.session));
const results: OpResult[] =
args.typingAnimations === false
@@ -128,5 +135,6 @@ export async function runEditorCode(args: RunEditorCodeArgs): Promise<string> {
const failed = results.filter((r) => !r.ok).length;
span?.setAttr('ops.failed', failed);
if (failed > 0) span?.setAttr('error.kind', 'apply');
- return summarize(results);
+ const after = snapshotNodes(serializeWithXml(args.session));
+ return describeEffect(summarize(results), diffNodes(before, after));
}
diff --git a/services/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts b/services/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts
index b37d04a67a..bbfac0572d 100644
--- a/services/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts
+++ b/services/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts
@@ -2,6 +2,7 @@ import type { LanguageModel, LanguageModelUsage } from 'ai';
import { describe, expect, it } from 'vitest';
import type { coder } from '../agents';
import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { serializeWithXml } from '../utils';
import { mockAwarenessSource } from '../awareness/awareness-source';
import { Doc } from '../doc/doc';
import { TokenTracker } from '../token-tracker';
@@ -220,3 +221,117 @@ describe('dispatch -- onInputAvailable early launch', () => {
expect(tasks.sort()).toEqual(['other edit', 'this edit']);
});
});
+
+describe('conflicting parallel dispatches', () => {
+ /** Harness that records coder start/finish order and lets each run be
+ * released on demand, so overlap is observable rather than timing-dependent. */
+ function setupOrdered() {
+ const session = createEditingSession();
+ loadMarkdown(session, '# Title\n\nalpha\n\nbravo\n');
+ const ids = [...indexXmlRanges(serializeWithXml(session)).byId.keys()];
+
+ const events: string[] = [];
+ const gates = new Map<string, () => void>();
+
+ const dispatch = createDispatchTool({
+ session,
+ makeChildModel: () => childModel,
+ tracker: new TokenTracker(),
+ runner: () => [],
+ makeWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ runTask: async (_session, task) => {
+ events.push(`start:${task}`);
+ await new Promise<void>((resolve) => gates.set(task, resolve));
+ events.push(`end:${task}`);
+ return coderResult;
+ },
+ });
+ const release = async (task: string) => {
+ // Let the coder that owns this gate actually register first.
+ for (let i = 0; i < 50 && !gates.has(task); i++) await Promise.resolve();
+ gates.get(task)?.();
+ await new Promise((r) => setTimeout(r, 0));
+ };
+ return { dispatch, events, release, ids };
+ }
+
+ it('runs edits on different nodes concurrently', async () => {
+ const { dispatch, events, release, ids } = setupOrdered();
+ const a = `edit ${ids[0]}`;
+ const b = `edit ${ids[1]}`;
+
+ const runA = dispatch.tool.execute!({ editing_instruction: a }, {
+ toolCallId: 'a',
+ messages: [],
+ } as never);
+ const runB = dispatch.tool.execute!({ editing_instruction: b }, {
+ toolCallId: 'b',
+ messages: [],
+ } as never);
+
+ await new Promise((r) => setTimeout(r, 0));
+ // Both are in flight before either finishes.
+ expect(events.filter((e) => e.startsWith('start:'))).toHaveLength(2);
+
+ await release(a);
+ await release(b);
+ await Promise.all([runA, runB]);
+ });
+
+ it('serializes edits that target the same node', async () => {
+ const { dispatch, events, release, ids } = setupOrdered();
+ const shared = ids[0]!;
+ const a = `first touching ${shared}`;
+ const b = `second touching ${shared}`;
+
+ const runA = dispatch.tool.execute!({ editing_instruction: a }, {
+ toolCallId: 'a',
+ messages: [],
+ } as never);
+ const runB = dispatch.tool.execute!({ editing_instruction: b }, {
+ toolCallId: 'b',
+ messages: [],
+ } as never);
+
+ await new Promise((r) => setTimeout(r, 0));
+ // The second coder must not have started while the first holds the node.
+ expect(events).toEqual([`start:${a}`]);
+
+ await release(a);
+ await release(b);
+ await Promise.all([runA, runB]);
+
+ expect(events).toEqual([
+ `start:${a}`,
+ `end:${a}`,
+ `start:${b}`,
+ `end:${b}`,
+ ]);
+ });
+
+ it('does not serialize on prose that merely looks like an id', async () => {
+ const { dispatch, events, release } = setupOrdered();
+ const a = 'rewrite the Suggested constraint paragraph';
+ const b = 'rewrite the Suggested constraint heading';
+
+ const runA = dispatch.tool.execute!({ editing_instruction: a }, {
+ toolCallId: 'a',
+ messages: [],
+ } as never);
+ const runB = dispatch.tool.execute!({ editing_instruction: b }, {
+ toolCallId: 'b',
+ messages: [],
+ } as never);
+
+ await new Promise((r) => setTimeout(r, 0));
+ expect(events.filter((e) => e.startsWith('start:'))).toHaveLength(2);
+
+ await release(a);
+ await release(b);
+ await Promise.all([runA, runB]);
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts b/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts
index 226a8d9c3e..964f6d3bd8 100644
--- a/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts
+++ b/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts
@@ -165,6 +165,23 @@ export function computeContextRange(
};
}
+/**
+ * Node ids an instruction actually refers to.
+ *
+ * Filtered against ids present in the document so ordinary prose that happens
+ * to match the id shape (`Suggested`, `constraint`) doesn't create phantom
+ * conflicts that serialize unrelated edits.
+ */
+export function targetIds(
+ instruction: string,
+ session: LexicalSession
+): Set<string> {
+ const candidates = instruction.match(ID_PATTERN);
+ if (!candidates) return new Set();
+ const { byId } = indexXmlRanges(serializeWithXml(session));
+ return new Set(candidates.filter((id) => byId.has(id)));
+}
+
/** Lines of context to show a writer around its target region. Generous on
* purpose: a roomy window means the writer rarely has to call `readDocument`. */
const MIN_WINDOW_LINES = 20;
@@ -201,11 +218,18 @@ export type DispatchEditTrace = {
coderStartedAt: number;
coderFinishedAt: number;
runCodeAt: number[];
+ /** Reply text per runCode call, positionally aligned with `runCodeAt`. */
+ runCodeResults: string[];
};
/** One runCode invocation as recorded for the trace: the code plus any content
* the writer composed and passed alongside it. */
-export type CoderRunCode = { code: string; snippets?: Record<string, string> };
+export type CoderRunCode = {
+ code: string;
+ snippets?: Record<string, string>;
+ /** The reply this call produced, as the coder saw it. */
+ result?: string;
+};
export type DispatchToolOptions = {
session: LexicalSession;
@@ -221,6 +245,8 @@ export type DispatchToolOptions = {
sleep?: (ms: number) => Promise<void>;
signal?: AbortSignal;
makeWriter: () => Promise<Writer>;
+ /** Per-coder step cap, forwarded to every coder this tool spawns. */
+ maxCoderSteps?: number;
runTask: typeof coder;
serialize?: (session: LexicalSession) => string;
onOps?: RunCodeToolOptions['onOps'];
@@ -257,6 +283,7 @@ export function createDispatchTool(opts: DispatchToolOptions) {
sleep,
signal,
makeWriter,
+ maxCoderSteps,
runTask,
runner,
onOps,
@@ -275,12 +302,38 @@ export function createDispatchTool(opts: DispatchToolOptions) {
// Coders already started from onInputAvailable, keyed by tool call id.
const calls = new Map<string, EditRun>();
+ /**
+ * Node ids each in-flight coder is working on, plus a promise that settles
+ * when it finishes. Parallel coders share one `LexicalSession`, so two
+ * dispatches aimed at the same node interleave their edits on the same
+ * subtree — the largest failure class in the trace corpus, and the one that
+ * produces silently corrupted documents rather than clean failures.
+ */
+ const inFlight: { ids: Set<string>; done: Promise<unknown> }[] = [];
+
+ /** Wait out any in-flight coder whose target ids overlap this instruction's.
+ *
+ * Independent edits still run fully in parallel; only the ones that would
+ * collide are serialized, so this costs latency exactly where the
+ * alternative is corruption. */
+ async function awaitConflicts(ids: Set<string>): Promise<void> {
+ if (ids.size === 0) return;
+ const blockers = inFlight
+ .filter((entry) => [...ids].some((id) => entry.ids.has(id)))
+ .map((entry) => entry.done);
+ if (blockers.length > 0) await Promise.allSettled(blockers);
+ }
+
async function runEdit(
edit: DispatchEdit,
trace: DispatchEditTrace,
childModel: LanguageModel,
span: Span
): Promise<CoderRun> {
+ // Hold off until nothing conflicting is running, THEN serialize the
+ // document — so this coder's window reflects the conflicting edit rather
+ // than a snapshot taken before it landed.
+ await awaitConflicts(targetIds(edit.editing_instruction, session));
try {
// Serialized at launch time so an edit launched early sees whatever earlier
// coders have already applied.
@@ -302,6 +355,7 @@ export function createDispatchTool(opts: DispatchToolOptions) {
doc,
awarenessSource,
context,
+ maxSteps: maxCoderSteps,
request,
params,
typingAnimations,
@@ -310,6 +364,7 @@ export function createDispatchTool(opts: DispatchToolOptions) {
runner,
onOps,
onRunCode: () => trace.runCodeAt.push(Date.now()),
+ onRunCodeResult: (result) => trace.runCodeResults.push(result),
span,
}
);
@@ -345,6 +400,7 @@ export function createDispatchTool(opts: DispatchToolOptions) {
coderStartedAt: Date.now(),
coderFinishedAt: 0,
runCodeAt: [],
+ runCodeResults: [],
};
// runEdit ends the span in its finally, so streamed runs that reject
// before `execute` joins them still close it.
@@ -364,6 +420,21 @@ export function createDispatchTool(opts: DispatchToolOptions) {
// A streamed run can reject before `execute` awaits it; keep that rejection
// for the join instead of letting it escape as an unhandled rejection.
entry.run.catch(() => {});
+
+ // Publish this coder's targets before it starts so a later dispatch in the
+ // same batch can see the conflict. Ids are resolved against the document as
+ // it stands now, which is what a concurrent sibling would collide with.
+ const claimed =
+ typeof edit.editing_instruction === 'string'
+ ? targetIds(edit.editing_instruction, session)
+ : new Set<string>();
+ const record = { ids: claimed, done: entry.run };
+ inFlight.push(record);
+ void entry.run.finally(() => {
+ const i = inFlight.indexOf(record);
+ if (i !== -1) inFlight.splice(i, 1);
+ });
+
calls.set(toolCallId, entry);
return entry;
}
@@ -390,9 +461,9 @@ export function createDispatchTool(opts: DispatchToolOptions) {
const codes = result.steps
.flatMap((step) => step.toolCalls)
.filter((call) => call.toolName === 'runCode')
- .map((call) => {
+ .map((call, i) => {
const { code, snippets } = call.input as CoderRunCode;
- return { code, snippets };
+ return { code, snippets, result: entry.trace.runCodeResults[i] };
});
onCoderResult(codes);
}
diff --git a/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts b/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts
new file mode 100644
index 0000000000..09ad234cd0
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { mockAwarenessSource } from '../awareness/awareness-source';
+import { Doc } from '../doc/doc';
+import { createRunCodeTool } from './run-code';
+
+/**
+ * The SHAPES of every non-string snippet value seen in the production corpus.
+ *
+ * Content is synthetic on purpose — the corpus text is real user documents, and
+ * only the shape is what the schema has to accept. All 51 non-string snippet
+ * values across 495 prod sessions are one of these.
+ * The strict `Record<string, string>` schema rejected every one, and a rejected
+ * tool call costs the coder its whole step — it has to retry from scratch.
+ */
+const REAL_PROD_SNIPPETS = {
+ 'array of strings (45 of 51 occurrences)': {
+ items: ['first list entry', 'second list entry'],
+ },
+ 'array with a single entry': { listItems: ['only entry'] },
+} as const;
+
+function setup() {
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ const applied: unknown[] = [];
+ const tool = createRunCodeTool({
+ session,
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ runner: (_ids, _code, snippets) => {
+ applied.push(snippets);
+ return [];
+ },
+ });
+ return { tool, applied };
+}
+
+const callOptions = { toolCallId: 'c1', messages: [] } as never;
+
+/** `tool()` widens inputSchema to FlexibleSchema; we know it's the zod object. */
+function schemaOf(tool: ReturnType<typeof createRunCodeTool>) {
+ return tool.inputSchema as unknown as {
+ safeParse: (v: unknown) => { success: boolean };
+ };
+}
+
+describe('runCode snippets', () => {
+ it('accepts a plain string record', () => {
+ const parsed = schemaOf(setup().tool).safeParse({
+ code: 'editor.setText("a", snippets.body)',
+ snippets: { body: 'text' },
+ });
+ expect(parsed.success).toBe(true);
+ });
+
+ for (const [name, snippets] of Object.entries(REAL_PROD_SNIPPETS)) {
+ it(`accepts ${name}`, () => {
+ const parsed = schemaOf(setup().tool).safeParse({
+ code: 'editor.setText("a", snippets.items)',
+ snippets,
+ });
+ expect(parsed.success).toBe(true);
+ });
+ }
+
+ it('joins array values with newlines before the sandbox sees them', async () => {
+ const { tool, applied } = setup();
+ await tool.execute!(
+ {
+ code: 'editor.setText("a", snippets.items)',
+ snippets: { items: ['first', 'second'] },
+ },
+ callOptions
+ );
+ // The sandbox exposes `snippets` as plain strings, and every editor
+ // primitive takes text — joining is what the coder meant by passing a list.
+ expect(applied[0]).toEqual({ items: 'first\nsecond' });
+ });
+
+ it('leaves string values untouched', async () => {
+ const { tool, applied } = setup();
+ await tool.execute!(
+ { code: 'editor.setText("a", snippets.body)', snippets: { body: 'x\ny' } },
+ callOptions
+ );
+ expect(applied[0]).toEqual({ body: 'x\ny' });
+ });
+
+ it('still rejects a value that is neither string nor string[]', () => {
+ const parsed = schemaOf(setup().tool).safeParse({
+ code: 'x',
+ snippets: { body: { nested: true } },
+ });
+ expect(parsed.success).toBe(false);
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/tools/run-code.ts b/services/ai-editing-worker/src/ai-editing/tools/run-code.ts
index ea86b937c7..acd3659fbe 100644
--- a/services/ai-editing-worker/src/ai-editing/tools/run-code.ts
+++ b/services/ai-editing-worker/src/ai-editing/tools/run-code.ts
@@ -21,8 +21,30 @@ export type RunCodeToolOptions = {
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;
};
+/** Collapse array snippet values to newline-joined text.
+ *
+ * The sandbox exposes `snippets` as a plain object of strings, and every
+ * editor primitive takes text, so joining is what the coder wanted anyway when
+ * it passed a list. */
+function flattenSnippets(
+ snippets: Record<string, string | string[]> | undefined
+): Record<string, string> | undefined {
+ if (!snippets) return undefined;
+ return Object.fromEntries(
+ Object.entries(snippets).map(([key, value]) => [
+ key,
+ Array.isArray(value) ? value.join('\n') : value,
+ ])
+ );
+}
+
/** 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. */
@@ -33,14 +55,22 @@ export function createRunCodeTool(opts: RunCodeToolOptions) {
inputSchema: z.object({
code: z.string(),
snippets: z
- .record(z.string(), z.string())
+ .record(
+ z.string(),
+ // Coders routinely send an array when composing a list. A strict
+ // string-only record rejected those calls, and the coder's only
+ // recourse was to retry the whole step — 45 such retries across the
+ // prod corpus. Accept the shape it actually produces.
+ z.union([z.string(), z.array(z.string())])
+ )
.optional()
.describe(
- 'all text content your code relies on. referenced as `snippets.KEY` in code rather than embedded in code. No escaping is necessary for snippet definitions, just use raw loose text.'
+ 'all text content your code inserts: key -> exact content. reference each as `snippets.KEY` in `code` instead of embedding it as a string literal (avoids escaping errors). a value may be an array of strings for list content.'
),
}),
execute: async ({ code, snippets }) => {
- opts.onRunCode?.(snippets);
+ const flattened = flattenSnippets(snippets);
+ opts.onRunCode?.(flattened);
const span = opts.span
? opts.span.span('edit.run_code')
: Telemetry.span('edit.run_code');
@@ -52,7 +82,7 @@ export function createRunCodeTool(opts: RunCodeToolOptions) {
doc: opts.doc,
code,
awarenessSource: opts.awarenessSource,
- snippets,
+ snippets: flattened,
params: opts.params,
typingAnimations: opts.typingAnimations,
sleep: opts.sleep,
@@ -60,6 +90,7 @@ export function createRunCodeTool(opts: RunCodeToolOptions) {
onOps: opts.onOps,
span,
});
+ opts.onRunCodeResult?.(result);
span.setAttr('result', result.startsWith('error:') ? 'error' : 'ok');
return result;
} catch (e) {
diff --git a/services/ai-editing-worker/src/ai-fallback.test.ts b/services/ai-editing-worker/src/ai-fallback.test.ts
new file mode 100644
index 0000000000..c9f4adb8d7
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-fallback.test.ts
@@ -0,0 +1,12 @@
+import { defaultShouldRetryThisError } from 'ai-fallback';
+import { describe, expect, it } from 'vitest';
+
+describe('ai-fallback patch', () => {
+ it('falls back when a provider requires payment', () => {
+ const error = Object.assign(new Error('Payment required'), {
+ statusCode: 402,
+ });
+
+ expect(defaultShouldRetryThisError(error)).toBe(true);
+ });
+});
diff --git a/services/ai-editing-worker/src/editor-sandbox-code.ts b/services/ai-editing-worker/src/editor-sandbox-code.ts
index 6edcdb8889..c9a6977d52 100644
--- a/services/ai-editing-worker/src/editor-sandbox-code.ts
+++ b/services/ai-editing-worker/src/editor-sandbox-code.ts
@@ -1,3 +1,3 @@
// Auto-generated by scripts/generate-sandbox.ts — do not edit.
// Source of truth: src/ai-editing/editor/document-editor.ts
-export const SANDBOX_CODE = "class EditError extends Error {\n constructor(message) {\n super(message);\n this.name = \"EditError\";\n }\n}\n\nclass DocumentEditor {\n ops = [];\n valid;\n refs;\n refIdx = 0;\n constructor(opts) {\n this.valid = new Set(opts.validIds);\n this.refs = opts.refs;\n }\n push(op) {\n this.ops.push(op);\n return this;\n }\n requireId(id) {\n if (!this.valid.has(id)) {\n throw new EditError(`unknown id \"${id}\"`);\n }\n }\n requireMatch(match) {\n if (match.length === 0)\n throw new EditError(\"match string is empty\");\n }\n mintRef() {\n const ref = this.refs[this.refIdx++];\n if (!ref) {\n throw new EditError(\"too many inserts in one snippet (id pool exhausted)\");\n }\n this.valid.add(ref);\n return ref;\n }\n drain() {\n const out = this.ops;\n this.ops = [];\n return out;\n }\n format(id, match, format, on = true, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({\n kind: \"formatText\",\n node: id,\n match,\n format,\n on,\n scope\n });\n }\n bold(id, match, scope) {\n return this.format(id, match, \"bold\", true, scope);\n }\n italic(id, match, scope) {\n return this.format(id, match, \"italic\", true, scope);\n }\n underline(id, match, scope) {\n return this.format(id, match, \"underline\", true, scope);\n }\n strike(id, match, scope) {\n return this.format(id, match, \"strike\", true, scope);\n }\n inlineCode(id, match, scope) {\n return this.format(id, match, \"code\", true, scope);\n }\n unbold(id, match, scope) {\n return this.format(id, match, \"bold\", false, scope);\n }\n unitalic(id, match, scope) {\n return this.format(id, match, \"italic\", false, scope);\n }\n ununderline(id, match, scope) {\n return this.format(id, match, \"underline\", false, scope);\n }\n unstrike(id, match, scope) {\n return this.format(id, match, \"strike\", false, scope);\n }\n uninlineCode(id, match, scope) {\n return this.format(id, match, \"code\", false, scope);\n }\n clearFormat(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n if (match !== undefined)\n this.requireMatch(match);\n return this.push({ kind: \"clearFormat\", node: id, match, scope });\n }\n clearAllFormat(id) {\n return this.clearFormat(id);\n }\n highlight(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"markText\", node: id, match, on: true, scope });\n }\n unhighlight(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"markText\", node: id, match, on: false, scope });\n }\n link(id, match, url, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"linkText\", node: id, match, url, scope });\n }\n unlink(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"linkText\", node: id, match, url: null, scope });\n }\n formatNode(node, format, on = true) {\n this.requireId(node);\n return this.push({ kind: \"formatNode\", node, format, on });\n }\n boldNode(node) {\n return this.formatNode(node, \"bold\");\n }\n italicNode(node) {\n return this.formatNode(node, \"italic\");\n }\n underlineNode(node) {\n return this.formatNode(node, \"underline\");\n }\n strikeNode(node) {\n return this.formatNode(node, \"strike\");\n }\n codeNode(node) {\n return this.formatNode(node, \"code\");\n }\n clearNodeFormat(node) {\n this.requireId(node);\n return this.push({ kind: \"clearNodeFormat\", node });\n }\n setText(id, text) {\n this.requireId(id);\n return this.push({ kind: \"setText\", node: id, text });\n }\n setEquation(id, tex) {\n this.requireId(id);\n return this.push({ kind: \"setEquation\", node: id, tex });\n }\n replace(id, find, to, scope = { kind: \"all\" }) {\n this.requireId(id);\n if (find.length === 0)\n throw new EditError(\"find string is empty\");\n return this.push({ kind: \"replaceText\", node: id, find, to, scope });\n }\n appendText(id, text) {\n this.requireId(id);\n return this.push({ kind: \"appendText\", node: id, text });\n }\n prependText(id, text) {\n this.requireId(id);\n return this.push({ kind: \"prependText\", node: id, text });\n }\n setBlockType(id, args) {\n this.requireId(id);\n return this.push({ kind: \"setBlockType\", node: id, ...args });\n }\n requireLanguage(language) {\n if (typeof language !== \"string\" || language.trim().length === 0)\n throw new EditError(\"code block language is required\");\n }\n convertToParagraph(id) {\n return this.setBlockType(id, { block: \"paragraph\" });\n }\n convertToHeading(id, level) {\n if (level < 1 || level > 6)\n throw new EditError(`heading level must be 1-6, got ${level}`);\n return this.setBlockType(id, { block: \"heading\", level });\n }\n convertToQuote(id) {\n return this.setBlockType(id, { block: \"quote\" });\n }\n convertToCodeBlock(id, language) {\n this.requireLanguage(language);\n return this.setBlockType(id, { block: \"code\", language });\n }\n setLanguage(id, language) {\n return this.convertToCodeBlock(id, language);\n }\n toList(idOrIds, list) {\n const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];\n if (ids.length === 0)\n throw new EditError(\"list requires at least one block\");\n for (const id of ids)\n this.requireId(id);\n return this.push({ kind: \"setListType\", nodes: ids, list });\n }\n bulletList(idOrIds) {\n return this.toList(idOrIds, \"bullet\");\n }\n numberedList(idOrIds) {\n return this.toList(idOrIds, \"number\");\n }\n checklist(idOrIds) {\n return this.toList(idOrIds, \"check\");\n }\n setListType(id, list) {\n return this.toList(id, list);\n }\n check(id) {\n return this.setChecked(id, true);\n }\n uncheck(id) {\n return this.setChecked(id, false);\n }\n setChecked(id, checked) {\n this.requireId(id);\n return this.push({ kind: \"setChecked\", node: id, checked });\n }\n indent(id, by = 1) {\n this.requireId(id);\n return this.push({\n kind: \"setIndent\",\n node: id,\n indent: by >= 0 ? \"in\" : \"out\"\n });\n }\n outdent(id, by = 1) {\n return this.indent(id, -Math.abs(by));\n }\n setIndent(id, level) {\n this.requireId(id);\n if (level < 0)\n throw new EditError(`indent level must be >= 0, got ${level}`);\n return this.push({ kind: \"setIndent\", node: id, indent: level });\n }\n insertListItemAfter(id, text, list = \"bullet\") {\n this.requireId(id);\n const ref = this.mintRef();\n this.push({ kind: \"insertListItemAfter\", ref, node: id, text, list });\n return ref;\n }\n insertListItemBefore(id, text, list = \"bullet\") {\n this.requireId(id);\n const ref = this.mintRef();\n this.push({ kind: \"insertListItemBefore\", ref, node: id, text, list });\n return ref;\n }\n appendListItem(listId, text) {\n this.requireId(listId);\n const ref = this.mintRef();\n this.push({ kind: \"appendListItem\", ref, node: listId, text });\n return ref;\n }\n prependListItem(listId, text) {\n this.requireId(listId);\n const ref = this.mintRef();\n this.push({ kind: \"prependListItem\", ref, node: listId, text });\n return ref;\n }\n removeListItem(id) {\n this.requireId(id);\n return this.push({ kind: \"removeListItem\", node: id });\n }\n insert(spec, at) {\n this.requireAt(at);\n const ref = this.mintRef();\n this.push({ kind: \"insertNode\", ref, spec, at });\n return ref;\n }\n requireAt(at) {\n if (\"after\" in at)\n this.requireId(at.after);\n else if (\"before\" in at)\n this.requireId(at.before);\n }\n insertParagraphAfter(id, text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { after: id });\n }\n insertParagraphBefore(id, text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { before: id });\n }\n insertHeadingAfter(id, level, text = \"\") {\n return this.insert({ block: \"heading\", level, text }, { after: id });\n }\n insertHeadingBefore(id, level, text = \"\") {\n return this.insert({ block: \"heading\", level, text }, { before: id });\n }\n insertQuoteAfter(id, text = \"\") {\n return this.insert({ block: \"quote\", text }, { after: id });\n }\n insertCodeBlockAfter(id, language, text = \"\") {\n this.requireLanguage(language);\n return this.insert({ block: \"code\", language, text }, { after: id });\n }\n insertBlockAfter(id, spec) {\n return this.insert(spec, { after: id });\n }\n insertBlockBefore(id, spec) {\n return this.insert(spec, { before: id });\n }\n appendParagraph(text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { appendToRoot: true });\n }\n prependParagraph(text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { prependToRoot: true });\n }\n appendBlock(spec) {\n return this.insert(spec, { appendToRoot: true });\n }\n prependBlock(spec) {\n return this.insert(spec, { prependToRoot: true });\n }\n move(id, at) {\n this.requireId(id);\n this.requireAt(at);\n return this.push({ kind: \"moveNode\", node: id, at });\n }\n remove(id) {\n this.requireId(id);\n return this.push({ kind: \"removeNode\", node: id });\n }\n removeMany(ids) {\n for (const id of ids)\n this.remove(id);\n return this;\n }\n merge(ids, separator = \" \") {\n if (ids.length < 2)\n throw new EditError(\"merge requires at least two blocks\");\n for (const id of ids)\n this.requireId(id);\n return this.push({ kind: \"mergeBlocks\", nodes: ids, separator });\n }\n insertTableAfter(id, rows) {\n return this.buildTable(rows, { after: id });\n }\n insertTableBefore(id, rows) {\n return this.buildTable(rows, { before: id });\n }\n appendTable(rows) {\n return this.buildTable(rows, { appendToRoot: true });\n }\n buildTable(rows, at) {\n if (rows.length === 0)\n throw new EditError(\"table requires at least one row\");\n const empty = rows.map((row) => row.map(() => \"\"));\n const ref = this.insert({ block: \"table\", rows: empty }, at);\n rows.forEach((row, r) => void row.forEach((cell, c) => {\n if (cell)\n this.setCell(ref, r, c, cell);\n }));\n return ref;\n }\n setCell(table, row, col, text) {\n this.requireId(table);\n this.requireCell(row, col);\n return this.push({ kind: \"setCell\", table, row, col, text });\n }\n addRow(table, at) {\n this.requireId(table);\n return this.push({ kind: \"addRow\", table, at });\n }\n addColumn(table, at) {\n this.requireId(table);\n return this.push({ kind: \"addColumn\", table, at });\n }\n removeRow(table, row) {\n this.requireId(table);\n this.requireCell(row, 0);\n return this.push({ kind: \"removeRow\", table, row });\n }\n removeColumn(table, col) {\n this.requireId(table);\n this.requireCell(0, col);\n return this.push({ kind: \"removeColumn\", table, col });\n }\n requireCell(row, col) {\n if (row < 0 || col < 0)\n throw new EditError(`cell indices must be >= 0, got (${row}, ${col})`);\n }\n insertDivider(afterId) {\n return this.insert({ block: \"divider\" }, { after: afterId });\n }\n insertImage(afterId, img) {\n return this.insert({ block: \"image\", ...img }, { after: afterId });\n }\n insertVideo(afterId, vid) {\n return this.insert({ block: \"video\", ...vid }, { after: afterId });\n }\n insertEquation(afterId, tex) {\n return this.insert({ block: \"equation\", tex }, { after: afterId });\n }\n insertInlineEquation(blockId, at, tex) {\n return this.insertInline(blockId, at, { inline: \"equation\", tex });\n }\n insertTextAfterInline(inlineRef, text) {\n return this.push({\n kind: \"insertTextAfterInline\",\n inline: inlineRef,\n text\n });\n }\n insertLineBreak(blockId, at) {\n return this.insertInline(blockId, at, { inline: \"linebreak\" });\n }\n insertDate(blockId, at, isoDate, displayFormat) {\n return this.insertInline(blockId, at, {\n inline: \"date\",\n date: isoDate,\n displayFormat\n });\n }\n insertInline(id, at, spec) {\n this.requireId(id);\n if (at < 0)\n throw new EditError(`inline offset must be >= 0, got ${at}`);\n const ref = this.mintRef();\n this.push({ kind: \"insertInline\", ref, node: id, at, spec });\n return ref;\n }\n insertMention(blockId, at, mention) {\n return this.insertInline(blockId, at, { inline: \"mention\", mention });\n }\n mentionUser(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"user\", ...entity });\n }\n mentionContact(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"contact\", ...entity });\n }\n mentionGroup(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"group\", ...entity });\n }\n mentionDocument(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"document\", ...entity });\n }\n setImageAlt(id, alt) {\n this.requireId(id);\n return this.push({ kind: \"setImageAlt\", node: id, alt });\n }\n setImageUrl(id, url) {\n this.requireId(id);\n return this.push({ kind: \"setImageUrl\", node: id, url });\n }\n setVideoUrl(id, url) {\n this.requireId(id);\n return this.push({ kind: \"setVideoUrl\", node: id, url });\n }\n setVideoControls(id, controls) {\n this.requireId(id);\n return this.push({ kind: \"setVideoControls\", node: id, controls });\n }\n setDate(id, date, displayFormat) {\n this.requireId(id);\n return this.push({ kind: \"setDate\", node: id, date, displayFormat });\n }\n}";
+export const SANDBOX_CODE = "class EditError extends Error {\n constructor(message) {\n super(message);\n this.name = \"EditError\";\n }\n}\n\nfunction describeBadId(value) {\n if (value === null)\n return \"null\";\n if (value === undefined)\n return \"undefined\";\n if (Array.isArray(value))\n return `an array of ${value.length}`;\n if (typeof value === \"object\") {\n const keys = Object.keys(value).slice(0, 4);\n return `an object with keys [${keys.join(\", \")}]`;\n }\n return `a ${typeof value} (${String(value)})`;\n}\n\nclass DocumentEditor {\n ops = [];\n valid;\n refs;\n refIdx = 0;\n constructor(opts) {\n this.valid = new Set(opts.validIds);\n this.refs = opts.refs;\n }\n push(op) {\n this.ops.push(op);\n return this;\n }\n requireId(id) {\n if (typeof id !== \"string\") {\n 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.\");\n }\n if (id.length === 0)\n throw new EditError(\"node id is an empty string\");\n if (!this.valid.has(id)) {\n throw new EditError(`unknown id \"${id}\"`);\n }\n }\n requireMatch(match) {\n if (match.length === 0)\n throw new EditError(\"match string is empty\");\n }\n mintRef() {\n const ref = this.refs[this.refIdx++];\n if (!ref) {\n throw new EditError(\"too many inserts in one snippet (id pool exhausted)\");\n }\n this.valid.add(ref);\n return ref;\n }\n drain() {\n const out = this.ops;\n this.ops = [];\n return out;\n }\n format(id, match, format, on = true, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({\n kind: \"formatText\",\n node: id,\n match,\n format,\n on,\n scope\n });\n }\n bold(id, match, scope) {\n return this.format(id, match, \"bold\", true, scope);\n }\n italic(id, match, scope) {\n return this.format(id, match, \"italic\", true, scope);\n }\n underline(id, match, scope) {\n return this.format(id, match, \"underline\", true, scope);\n }\n strike(id, match, scope) {\n return this.format(id, match, \"strike\", true, scope);\n }\n inlineCode(id, match, scope) {\n return this.format(id, match, \"code\", true, scope);\n }\n unbold(id, match, scope) {\n return this.format(id, match, \"bold\", false, scope);\n }\n unitalic(id, match, scope) {\n return this.format(id, match, \"italic\", false, scope);\n }\n ununderline(id, match, scope) {\n return this.format(id, match, \"underline\", false, scope);\n }\n unstrike(id, match, scope) {\n return this.format(id, match, \"strike\", false, scope);\n }\n uninlineCode(id, match, scope) {\n return this.format(id, match, \"code\", false, scope);\n }\n clearFormat(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n if (match !== undefined)\n this.requireMatch(match);\n return this.push({ kind: \"clearFormat\", node: id, match, scope });\n }\n clearAllFormat(id) {\n return this.clearFormat(id);\n }\n highlight(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"markText\", node: id, match, on: true, scope });\n }\n unhighlight(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"markText\", node: id, match, on: false, scope });\n }\n link(id, match, url, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"linkText\", node: id, match, url, scope });\n }\n unlink(id, match, scope = { kind: \"all\" }) {\n this.requireId(id);\n this.requireMatch(match);\n return this.push({ kind: \"linkText\", node: id, match, url: null, scope });\n }\n formatNode(node, format, on = true) {\n this.requireId(node);\n return this.push({ kind: \"formatNode\", node, format, on });\n }\n boldNode(node) {\n return this.formatNode(node, \"bold\");\n }\n italicNode(node) {\n return this.formatNode(node, \"italic\");\n }\n underlineNode(node) {\n return this.formatNode(node, \"underline\");\n }\n strikeNode(node) {\n return this.formatNode(node, \"strike\");\n }\n codeNode(node) {\n return this.formatNode(node, \"code\");\n }\n clearNodeFormat(node) {\n this.requireId(node);\n return this.push({ kind: \"clearNodeFormat\", node });\n }\n setText(id, text) {\n this.requireId(id);\n return this.push({ kind: \"setText\", node: id, text });\n }\n setEquation(id, tex) {\n this.requireId(id);\n return this.push({ kind: \"setEquation\", node: id, tex });\n }\n replace(id, find, to, scope = { kind: \"all\" }) {\n this.requireId(id);\n if (find.length === 0)\n throw new EditError(\"find string is empty\");\n return this.push({ kind: \"replaceText\", node: id, find, to, scope });\n }\n appendText(id, text) {\n this.requireId(id);\n return this.push({ kind: \"appendText\", node: id, text });\n }\n prependText(id, text) {\n this.requireId(id);\n return this.push({ kind: \"prependText\", node: id, text });\n }\n setBlockType(id, args) {\n this.requireId(id);\n return this.push({ kind: \"setBlockType\", node: id, ...args });\n }\n requireLanguage(language) {\n if (typeof language !== \"string\" || language.trim().length === 0)\n throw new EditError(\"code block language is required\");\n }\n convertToParagraph(id) {\n return this.setBlockType(id, { block: \"paragraph\" });\n }\n convertToHeading(id, level) {\n if (level < 1 || level > 6)\n throw new EditError(`heading level must be 1-6, got ${level}`);\n return this.setBlockType(id, { block: \"heading\", level });\n }\n convertToQuote(id) {\n return this.setBlockType(id, { block: \"quote\" });\n }\n convertToCodeBlock(id, language) {\n this.requireLanguage(language);\n return this.setBlockType(id, { block: \"code\", language });\n }\n setLanguage(id, language) {\n return this.convertToCodeBlock(id, language);\n }\n toList(idOrIds, list) {\n const ids = Array.isArray(idOrIds) ? idOrIds : [idOrIds];\n if (ids.length === 0)\n throw new EditError(\"list requires at least one block\");\n for (const id of ids)\n this.requireId(id);\n return this.push({ kind: \"setListType\", nodes: ids, list });\n }\n bulletList(idOrIds) {\n return this.toList(idOrIds, \"bullet\");\n }\n numberedList(idOrIds) {\n return this.toList(idOrIds, \"number\");\n }\n checklist(idOrIds) {\n return this.toList(idOrIds, \"check\");\n }\n setListType(id, list) {\n return this.toList(id, list);\n }\n check(id) {\n return this.setChecked(id, true);\n }\n uncheck(id) {\n return this.setChecked(id, false);\n }\n setChecked(id, checked) {\n this.requireId(id);\n return this.push({ kind: \"setChecked\", node: id, checked });\n }\n indent(id, by = 1) {\n this.requireId(id);\n return this.push({\n kind: \"setIndent\",\n node: id,\n indent: by >= 0 ? \"in\" : \"out\"\n });\n }\n outdent(id, by = 1) {\n return this.indent(id, -Math.abs(by));\n }\n setIndent(id, level) {\n this.requireId(id);\n if (level < 0)\n throw new EditError(`indent level must be >= 0, got ${level}`);\n return this.push({ kind: \"setIndent\", node: id, indent: level });\n }\n insertListItemAfter(id, text, list = \"bullet\") {\n this.requireId(id);\n const ref = this.mintRef();\n this.push({ kind: \"insertListItemAfter\", ref, node: id, text, list });\n return ref;\n }\n insertListItemBefore(id, text, list = \"bullet\") {\n this.requireId(id);\n const ref = this.mintRef();\n this.push({ kind: \"insertListItemBefore\", ref, node: id, text, list });\n return ref;\n }\n appendListItem(listId, text) {\n this.requireId(listId);\n const ref = this.mintRef();\n this.push({ kind: \"appendListItem\", ref, node: listId, text });\n return ref;\n }\n prependListItem(listId, text) {\n this.requireId(listId);\n const ref = this.mintRef();\n this.push({ kind: \"prependListItem\", ref, node: listId, text });\n return ref;\n }\n removeListItem(id) {\n this.requireId(id);\n return this.push({ kind: \"removeListItem\", node: id });\n }\n insert(spec, at) {\n this.requireAt(at);\n const ref = this.mintRef();\n this.push({ kind: \"insertNode\", ref, spec, at });\n return ref;\n }\n requireAt(at) {\n if (\"after\" in at)\n this.requireId(at.after);\n else if (\"before\" in at)\n this.requireId(at.before);\n }\n insertParagraphAfter(id, text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { after: id });\n }\n insertParagraphBefore(id, text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { before: id });\n }\n insertHeadingAfter(id, level, text = \"\") {\n return this.insert({ block: \"heading\", level, text }, { after: id });\n }\n insertHeadingBefore(id, level, text = \"\") {\n return this.insert({ block: \"heading\", level, text }, { before: id });\n }\n insertQuoteAfter(id, text = \"\") {\n return this.insert({ block: \"quote\", text }, { after: id });\n }\n insertCodeBlockAfter(id, language, text = \"\") {\n this.requireLanguage(language);\n return this.insert({ block: \"code\", language, text }, { after: id });\n }\n insertBlockAfter(id, spec) {\n return this.insert(spec, { after: id });\n }\n insertBlockBefore(id, spec) {\n return this.insert(spec, { before: id });\n }\n appendParagraph(text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { appendToRoot: true });\n }\n prependParagraph(text = \"\") {\n return this.insert({ block: \"paragraph\", text }, { prependToRoot: true });\n }\n appendBlock(spec) {\n return this.insert(spec, { appendToRoot: true });\n }\n prependBlock(spec) {\n return this.insert(spec, { prependToRoot: true });\n }\n move(id, at) {\n this.requireId(id);\n this.requireAt(at);\n return this.push({ kind: \"moveNode\", node: id, at });\n }\n remove(id) {\n this.requireId(id);\n return this.push({ kind: \"removeNode\", node: id });\n }\n removeMany(ids) {\n for (const id of ids)\n this.remove(id);\n return this;\n }\n merge(ids, separator = \" \") {\n if (ids.length < 2)\n throw new EditError(\"merge requires at least two blocks\");\n for (const id of ids)\n this.requireId(id);\n return this.push({ kind: \"mergeBlocks\", nodes: ids, separator });\n }\n insertTableAfter(id, rows) {\n return this.buildTable(rows, { after: id });\n }\n insertTableBefore(id, rows) {\n return this.buildTable(rows, { before: id });\n }\n appendTable(rows) {\n return this.buildTable(rows, { appendToRoot: true });\n }\n buildTable(rows, at) {\n if (rows.length === 0)\n throw new EditError(\"table requires at least one row\");\n const empty = rows.map((row) => row.map(() => \"\"));\n const ref = this.insert({ block: \"table\", rows: empty }, at);\n rows.forEach((row, r) => void row.forEach((cell, c) => {\n if (cell)\n this.setCell(ref, r, c, cell);\n }));\n return ref;\n }\n setCell(table, row, col, text) {\n this.requireId(table);\n this.requireCell(row, col);\n return this.push({ kind: \"setCell\", table, row, col, text });\n }\n addRow(table, at) {\n this.requireId(table);\n return this.push({ kind: \"addRow\", table, at });\n }\n addColumn(table, at) {\n this.requireId(table);\n return this.push({ kind: \"addColumn\", table, at });\n }\n removeRow(table, row) {\n this.requireId(table);\n this.requireCell(row, 0);\n return this.push({ kind: \"removeRow\", table, row });\n }\n removeColumn(table, col) {\n this.requireId(table);\n this.requireCell(0, col);\n return this.push({ kind: \"removeColumn\", table, col });\n }\n requireCell(row, col) {\n if (row < 0 || col < 0)\n throw new EditError(`cell indices must be >= 0, got (${row}, ${col})`);\n }\n insertDivider(afterId) {\n return this.insert({ block: \"divider\" }, { after: afterId });\n }\n insertImage(afterId, img) {\n return this.insert({ block: \"image\", ...img }, { after: afterId });\n }\n insertVideo(afterId, vid) {\n return this.insert({ block: \"video\", ...vid }, { after: afterId });\n }\n insertEquation(afterId, tex) {\n return this.insert({ block: \"equation\", tex }, { after: afterId });\n }\n insertInlineEquation(blockId, at, tex) {\n return this.insertInline(blockId, at, { inline: \"equation\", tex });\n }\n insertTextAfterInline(inlineRef, text) {\n return this.push({\n kind: \"insertTextAfterInline\",\n inline: inlineRef,\n text\n });\n }\n insertLineBreak(blockId, at) {\n return this.insertInline(blockId, at, { inline: \"linebreak\" });\n }\n insertDate(blockId, at, isoDate, displayFormat) {\n return this.insertInline(blockId, at, {\n inline: \"date\",\n date: isoDate,\n displayFormat\n });\n }\n insertInline(id, at, spec) {\n this.requireId(id);\n if (at < 0)\n throw new EditError(`inline offset must be >= 0, got ${at}`);\n const ref = this.mintRef();\n this.push({ kind: \"insertInline\", ref, node: id, at, spec });\n return ref;\n }\n insertMention(blockId, at, mention) {\n return this.insertInline(blockId, at, { inline: \"mention\", mention });\n }\n mentionUser(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"user\", ...entity });\n }\n mentionContact(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"contact\", ...entity });\n }\n mentionGroup(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"group\", ...entity });\n }\n mentionDocument(blockId, at, entity) {\n return this.insertMention(blockId, at, { kind: \"document\", ...entity });\n }\n setImageAlt(id, alt) {\n this.requireId(id);\n return this.push({ kind: \"setImageAlt\", node: id, alt });\n }\n setImageUrl(id, url) {\n this.requireId(id);\n return this.push({ kind: \"setImageUrl\", node: id, url });\n }\n setVideoUrl(id, url) {\n this.requireId(id);\n return this.push({ kind: \"setVideoUrl\", node: id, url });\n }\n setVideoControls(id, controls) {\n this.requireId(id);\n return this.push({ kind: \"setVideoControls\", node: id, controls });\n }\n setDate(id, date, displayFormat) {\n this.requireId(id);\n return this.push({ kind: \"setDate\", node: id, date, displayFormat });\n }\n}\nfunction editorMethodNames(target) {\n const names = new Set;\n for (let proto = target;proto && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {\n for (const key of Object.getOwnPropertyNames(proto)) {\n if (key === \"constructor\" || key.startsWith(\"_\"))\n continue;\n if (typeof target[key] === \"function\") {\n names.add(key);\n }\n }\n }\n return [...names];\n}\nfunction suggestMethods(wanted, names) {\n const normalizedWanted = wanted.toLowerCase();\n const scored = names.map((name) => {\n const normalizedName = name.toLowerCase();\n let score = 0;\n if (normalizedName === normalizedWanted)\n score = 1000;\n else if (normalizedName.includes(normalizedWanted) || normalizedWanted.includes(normalizedName)) {\n score = 100 + Math.min(normalizedName.length, normalizedWanted.length);\n } else {\n while (score < normalizedName.length && score < normalizedWanted.length && normalizedName[score] === normalizedWanted[score]) {\n score++;\n }\n }\n return { name, score };\n });\n scored.sort((a, b) => b.score - a.score);\n return scored.filter(({ score }) => score >= 3).slice(0, 3).map(({ name }) => name);\n}\nfunction createDocumentEditor(options) {\n const target = new DocumentEditor(options);\n return new Proxy(target, {\n get(editor, property) {\n const value = editor[property];\n if (value !== undefined || typeof property !== \"string\") {\n return typeof value === \"function\" ? value.bind(editor) : value;\n }\n return () => {\n const suggestions = suggestMethods(property, editorMethodNames(editor));\n 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.\");\n };\n }\n });\n}";
diff --git a/services/ai-editing-worker/src/endpoints/edit.ts b/services/ai-editing-worker/src/endpoints/edit.ts
index 954dc98e54..d44676890e 100644
--- a/services/ai-editing-worker/src/endpoints/edit.ts
+++ b/services/ai-editing-worker/src/endpoints/edit.ts
@@ -20,7 +20,22 @@ type Provider = 'anthropic' | 'cerebras' | 'openai';
const PROVIDERS = {
anthropic: { key: 'ANTHROPIC_API_KEY', create: createAnthropic },
cerebras: { key: 'CEREBRAS_API_KEY', create: createCerebras },
- openai: { key: 'OPENAI_API_KEY', create: createOpenAI },
+ // `.chat()` pins OpenAI to Chat Completions. The default factory uses the
+ // Responses API, which references reasoning items across steps by id — and
+ // this org has Zero Data Retention, so those ids are never persisted. Every
+ // multi-step edit then dies on:
+ // "Item with id 'rs_...' not found. Items are not persisted for Zero Data
+ // Retention organizations."
+ // The supervisor chain ends in gpt-5.5, so without this the last-resort
+ // fallback fails outright whenever both Anthropic models are unavailable —
+ // exactly when it is needed.
+ openai: {
+ key: 'OPENAI_API_KEY',
+ create: (opts: { apiKey: string }) => {
+ const provider = createOpenAI(opts);
+ return (modelId: string) => provider.chat(modelId);
+ },
+ },
} satisfies Record<
Provider,
{
diff --git a/services/ai-editing-worker/src/sandbox.ts b/services/ai-editing-worker/src/sandbox.ts
index f9f374d4e4..6d19e1228f 100644
--- a/services/ai-editing-worker/src/sandbox.ts
+++ b/services/ai-editing-worker/src/sandbox.ts
@@ -6,6 +6,7 @@ import {
newVariant,
} from 'quickjs-emscripten-core';
import type { DocumentOp } from './ai-editing/editor';
+import { sandboxInit } from './ai-editing/editor/sandbox-init';
import { SANDBOX_CODE } from './editor-sandbox-code';
/** Upper bound on inserts per snippet. The host mints the ids (QuickJS has no
@@ -38,7 +39,7 @@ export async function runInSandbox(
const refs = Array.from({ length: REF_POOL_SIZE }, () => nanoid());
const init = ctx.unwrapResult(
ctx.evalCode(
- `${SANDBOX_CODE}\nconst editor = new DocumentEditor({ validIds: ${JSON.stringify([...validIds])}, refs: ${JSON.stringify(refs)} });\nconst snippets = ${JSON.stringify(snippets ?? {})};`
+ `${SANDBOX_CODE}\n${sandboxInit(validIds, refs, snippets)}`
)
);
init.dispose();
diff --git a/services/ai-editing-worker/src/trace-log.test.ts b/services/ai-editing-worker/src/trace-log.test.ts
new file mode 100644
index 0000000000..51edb594e9
--- /dev/null
+++ b/services/ai-editing-worker/src/trace-log.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { renderTraceMarkdown, type TraceSession } from './trace-log';
+
+/**
+ * Regression tests for the trace renderer crashing on snippet shapes the coder
+ * actually produces.
+ *
+ * `renderTraceMarkdown` called `text.split('\n')` on every snippet value. A
+ * coder passing an array — 45 of the 51 non-string snippet values in the prod
+ * corpus — threw `text.split is not a function` and took down the render of the
+ * ENTIRE trace, so the session became undebuggable at exactly the moment
+ * someone wanted to debug it.
+ */
+function sessionWithSnippets(snippets: unknown): TraceSession {
+ return {
+ version: 1,
+ sessionId: 's1',
+ documentId: 'd1',
+ prompt: 'do the thing',
+ startedAt: new Date('2026-07-30T00:00:00Z').toISOString(),
+ steps: [
+ {
+ inputTokens: 10,
+ outputTokens: 5,
+ toolCalls: [
+ {
+ toolName: 'dispatch',
+ input: { editing_instruction: 'edit node abc' },
+ output: '✓ APPLIED\n\n<document>\n<doc/>\n</document>',
+ },
+ ],
+ },
+ ],
+ usage: [{ model: 'claude-haiku-4-5', inputTokens: 10, outputTokens: 5 }],
+ coderCodeBlocks: [[[{ code: 'editor.setText("a", snippets.x)', snippets: snippets as never }]]],
+ } as TraceSession;
+}
+
+describe('renderTraceMarkdown snippet rendering', () => {
+ it('renders a string snippet', () => {
+ const md = renderTraceMarkdown(sessionWithSnippets({ x: 'plain text' }));
+ expect(md).toContain('snippets.x');
+ expect(md).toContain('plain text');
+ });
+
+ it('renders an array snippet instead of throwing', () => {
+ const md = renderTraceMarkdown(
+ sessionWithSnippets({ items: ['first line', 'second line'] })
+ );
+ expect(md).toContain('snippets.items');
+ expect(md).toContain('first line');
+ expect(md).toContain('second line');
+ });
+
+ it('renders numeric and object snippet values', () => {
+ const md = renderTraceMarkdown(
+ sessionWithSnippets({ count: 3, card: { documentId: 'd9' } })
+ );
+ expect(md).toContain('snippets.count');
+ expect(md).toContain('snippets.card');
+ expect(md).toContain('d9');
+ });
+
+ it('renders when `snippets` itself is a bare string', () => {
+ // One prod session sent this; Object.entries over a string walks characters.
+ expect(() =>
+ renderTraceMarkdown(sessionWithSnippets('not an object' as never))
+ ).not.toThrow();
+ });
+
+ it('renders a malformed dispatch instruction verbatim rather than crashing', () => {
+ const session = sessionWithSnippets({ x: 'ok' });
+ (session.steps[0]!.toolCalls[0] as { input: unknown }).input = {
+ edits: [{ editing_instruction: 'legacy batch shape' }],
+ };
+ const md = renderTraceMarkdown(session);
+ expect(md).toContain('malformed');
+ });
+});
diff --git a/services/ai-editing-worker/src/trace-log.ts b/services/ai-editing-worker/src/trace-log.ts
index 9dfb9b3df9..a565fb9361 100644
--- a/services/ai-editing-worker/src/trace-log.ts
+++ b/services/ai-editing-worker/src/trace-log.ts
@@ -98,12 +98,24 @@ function relTime(ms: number | undefined, t0: number | undefined): string {
}
function indented(text: string): string {
- return text
+ return String(text)
.split('\n')
.map((l) => ` ${l}`)
.join('\n');
}
+/** Render a snippet value for the trace.
+ *
+ * The schema asks for `Record<string, string>`, but coders regularly send an
+ * array (composing a list) or an object, and the whole trace used to fail to
+ * render because of it. A trace is a debugging artifact — it must survive
+ * whatever the model actually produced. */
+function formatSnippetValue(value: unknown): string {
+ if (typeof value === 'string') return value;
+ if (Array.isArray(value)) return value.map((v) => String(v)).join('\n');
+ return JSON.stringify(value, null, 2) ?? String(value);
+}
+
/** Step header timing, e.g. `· 0.9s · t+1.4s` (this step / cumulative). */
function formatTiming(durationMs?: number, elapsedMs?: number): string {
const parts: string[] = [];
@@ -139,7 +151,7 @@ function formatEditEntry(
parts.push(`\n \`\`\`js\n${indented(call.code)}\n \`\`\``);
for (const [key, value] of Object.entries(call.snippets ?? {})) {
parts.push(
- ` snippets.${key}:\n \`\`\`\n${indented(value)}\n \`\`\``
+ ` snippets.${key}:\n \`\`\`\n${indented(formatSnippetValue(value))}\n \`\`\``
);
}
}