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.

chore(ai worker): stream ai tool calls (#4706)

Wolf Mermelsteinb0ab8a5381e2
diff --git a/js/ai-editing-worker/scripts/edit.ts b/js/ai-editing-worker/scripts/edit.ts
index e448a0e01d..e5b644445f 100644
--- a/js/ai-editing-worker/scripts/edit.ts
+++ b/js/ai-editing-worker/scripts/edit.ts
@@ -9,8 +9,6 @@ const {
"supervisor-model": supervisorModelFlag,
"interpret-model": interpretModelFlag,
"coding-model": codingModelFlag,
- "snippet-model": snippetModelFlag,
- "snippet-high-model": snippetHighModelFlag,
interpret,
debug,
out,
@@ -27,8 +25,6 @@ const {
.option("supervisor-model", { type: "string", demandOption: true, describe: "provider:model for the supervisor" })
.option("interpret-model", { type: "string", demandOption: true, describe: "provider:model for the interpret pass" })
.option("coding-model", { type: "string", demandOption: true, describe: "provider:model for the coding agents" })
- .option("snippet-model", { type: "string", describe: "provider:model for snippet composition (defaults to --coding-model)" })
- .option("snippet-high-model", { type: "string", describe: "provider:model for effort:high snippet composition (defaults to --supervisor-model)" })
.option("interpret", { type: "boolean", default: true, describe: "run the intent-interpretation pass before editing (use --no-interpret to skip)" })
.option("debug", { type: "boolean", default: false, describe: "include the supervisor step trace + replay trace in the response" })
.option("out", { type: "string", describe: "write the replay trace JSON to this file (implies --debug)" })
@@ -79,8 +75,6 @@ const res = await fetch(`${workerUrl}/edit`, {
supervisor: [parseModel(supervisorModelFlag)],
interpret: [parseModel(interpretModelFlag)],
coding: [parseModel(codingModelFlag)],
- snippet: [parseModel(snippetModelFlag ?? codingModelFlag)],
- snippetHigh: [parseModel(snippetHighModelFlag ?? supervisorModelFlag)],
},
interpret,
debug: wantDebug,
diff --git a/js/ai-editing-worker/scripts/traces.ts b/js/ai-editing-worker/scripts/traces.ts
index 8f2f886eb9..9990010e8e 100644
--- a/js/ai-editing-worker/scripts/traces.ts
+++ b/js/ai-editing-worker/scripts/traces.ts
@@ -1,105 +1,104 @@
#!/usr/bin/env bun
-import { $ } from "bun";
import yargs from "yargs";
import { hideBin } from "yargs/helpers";
import { renderTraceMarkdown, type TraceSession } from "../src/trace-log";
-// Each env has its own D1 database (see wrangler.toml).
-const DB_BY_ENV: Record<string, string> = {
- local: "ai-editing-traces",
- dev: "ai-editing-traces",
- playground: "ai-editing-traces-playground",
- prod: "ai-editing-traces-prod",
+const WORKER_URL_BY_ENV: Record<string, string> = {
+ local: "http://localhost:8933",
+ dev: "https://ai-editing-worker-dev.macroverse.workers.dev",
+ playground: "https://ai-editing-worker-playground.macroverse.workers.dev",
+ prod: "https://ai-editing-worker.macroverse.workers.dev",
};
-const { env, id, latest, local, json, _ } = await yargs(hideBin(process.argv))
- .usage(
- "$0 <document-id> [--env dev] [--id <trace-id> | --latest] [--json] [--local]\n\n" +
- "Lists edit traces for a document; with --id/--latest dumps the full trace\n" +
- "(rendered markdown by default, or raw structured JSON with --json).",
- )
- .help()
- .option("env", {
- type: "string",
- default: "dev",
- choices: Object.keys(DB_BY_ENV),
- describe: "worker environment (selects the D1 database)",
- })
- .option("id", {
- type: "string",
- describe: "dump the full markdown for this trace id",
- })
- .option("latest", {
- type: "boolean",
- default: false,
- describe: "dump the full markdown for the newest trace of the document",
- })
- .option("local", {
- type: "boolean",
- default: false,
- describe: "query the local dev shard instead of the remote database",
- })
- .option("json", {
- type: "boolean",
- default: false,
- describe:
- "with --id/--latest, emit the raw structured JSON instead of rendered markdown",
- })
- .parse();
+const { env, id, latest, json, "worker-url": workerUrlOpt, _ } =
+ await yargs(hideBin(process.argv))
+ .usage(
+ "$0 <document-id> [--env dev] [--id <trace-id> | --latest] [--json] [--worker-url <url>]\n\n" +
+ "Lists edit traces for a document; with --id/--latest dumps the full trace\n" +
+ "(rendered markdown by default, or raw structured JSON with --json).\n\n" +
+ "Auth: reads INTERNAL_API_KEY from the environment.",
+ )
+ .help()
+ .option("env", {
+ type: "string",
+ default: "dev",
+ choices: Object.keys(WORKER_URL_BY_ENV),
+ describe: "worker environment",
+ })
+ .option("id", {
+ type: "string",
+ describe: "dump the full markdown for this trace id",
+ })
+ .option("latest", {
+ type: "boolean",
+ default: false,
+ describe: "dump the full markdown for the newest trace of the document",
+ })
+ .option("worker-url", {
+ type: "string",
+ describe: "override the worker base URL",
+ })
+ .option("json", {
+ type: "boolean",
+ default: false,
+ describe:
+ "with --id/--latest, emit the raw structured JSON instead of rendered markdown",
+ })
+ .parse();
const documentId = _[0] as string | undefined;
-if (!documentId && !id) {
+if (!documentId) {
console.error(
"Usage: bun run scripts/traces.ts <document-id> [--env dev] [--id <trace-id> | --latest]",
);
process.exit(1);
}
-const db = DB_BY_ENV[env]!;
-// The `local` env is only ever an on-disk SQLite shard (see wrangler.toml), so
-// there is no remote to hit — query it locally regardless of the --local flag.
-const location = local || env === "local" ? [] : ["--remote"];
-
-// Guard against breaking out of the SQL string literal. Ids are uuids / doc ids.
-function lit(value: string): string {
- if (value.includes("'")) {
- console.error(`invalid identifier: ${value}`);
- process.exit(1);
- }
- return `'${value}'`;
+const apiKey = process.env.INTERNAL_API_KEY;
+if (!apiKey) {
+ console.error("INTERNAL_API_KEY env var is not set");
+ process.exit(1);
}
-async function query(sql: string): Promise<Record<string, unknown>[]> {
- const res =
- await $`bunx wrangler d1 execute ${db} --env ${env} ${location} --json --command ${sql}`.quiet();
- const parsed = JSON.parse(res.stdout.toString()) as [{ results: unknown[] }];
- return parsed[0].results as Record<string, unknown>[];
+const workerBase = workerUrlOpt ?? WORKER_URL_BY_ENV[env]!;
+
+const res = await fetch(`${workerBase}/traces/${documentId}`, {
+ headers: { "x-internal-auth-key": apiKey },
+});
+if (!res.ok) {
+ console.error(`${res.status} ${res.statusText}: ${await res.text()}`);
+ process.exit(1);
}
+const { traces } = (await res.json()) as {
+ documentId: string;
+ count: number;
+ traces: { id: string; createdAt: number; session: TraceSession }[];
+};
+
if (id || latest) {
- const where = id
- ? `id = ${lit(id)}`
- : `document_id = ${lit(documentId!)} ORDER BY created_at DESC LIMIT 1`;
- const rows = await query(`SELECT trace_json FROM edit_traces WHERE ${where}`);
- if (rows.length === 0) {
+ const trace = id
+ ? traces.find((t) => t.id === id)
+ : traces[0];
+ if (!trace) {
console.error("no matching trace");
process.exit(1);
}
- const raw = String(rows[0]!.trace_json);
if (json) {
- process.stdout.write(raw);
+ process.stdout.write(JSON.stringify(trace.session, null, 2));
} else {
- process.stdout.write(
- renderTraceMarkdown(JSON.parse(raw) as TraceSession),
- );
+ process.stdout.write(renderTraceMarkdown(trace.session));
}
} else {
- const rows = await query(
- `SELECT id, datetime(created_at/1000,'unixepoch') AS at_utc, length(trace_json) AS json_chars FROM edit_traces WHERE document_id = ${lit(documentId!)} ORDER BY created_at DESC`,
- );
- if (rows.length === 0) {
+ if (traces.length === 0) {
console.error("no traces for that document");
process.exit(1);
}
- console.table(rows);
+ console.table(
+ traces.map((t) => ({
+ id: t.id,
+ at_utc: new Date(t.createdAt).toISOString(),
+ json_chars: JSON.stringify(t.session).length,
+ })),
+ );
}
diff --git a/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.test.ts b/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.test.ts
deleted file mode 100644
index 54fd482595..0000000000
--- a/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.test.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { buildPrompt } from './coder-prompt';
-
-describe('buildPrompt', () => {
- it('embeds verbatim snippets as JSON and lists pending ones by brief', () => {
- const prompt = buildPrompt('do the thing', '<p id="a1">hi</p>', {
- exact: 'verbatim value',
- intro: {
- brief: 'two paragraphs, casual tone',
- promise: Promise.resolve('x'),
- },
- });
- expect(prompt).toContain('"exact": "verbatim value"');
- expect(prompt).toContain('`snippets.intro` -- two paragraphs, casual tone');
- // the promise itself must never be stringified into the prompt
- expect(prompt).not.toContain('{}');
- expect(prompt).not.toContain('Promise');
- });
-
- it('lists only the pending block when all snippets are pending', () => {
- const prompt = buildPrompt('task', 'ctx', {
- body: { brief: 'one paragraph', promise: Promise.resolve('x') },
- });
- expect(prompt).not.toContain('const snippets =');
- expect(prompt).toContain('`snippets.body` -- one paragraph');
- });
-
- it('omits both snippet blocks when none are given', () => {
- const prompt = buildPrompt('task', 'ctx');
- expect(prompt).not.toContain('snippets');
- });
-});
diff --git a/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.ts b/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.ts
index e4a0bdeecb..28576d1f77 100644
--- a/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.ts
+++ b/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.ts
@@ -1,32 +1,11 @@
-import type { SnippetSource } from '../runtime';
-
export function buildPrompt(
task: string,
context: string,
- snippets?: SnippetSource
+ request?: string
): string {
- const verbatim: Record<string, string> = {};
- const pending: Array<[key: string, brief: string]> = [];
- for (const [key, value] of Object.entries(snippets ?? {})) {
- if (typeof value === 'string') verbatim[key] = value;
- else pending.push([key, value.brief]);
- }
- const snippetBlock =
- Object.keys(verbatim).length > 0
- ? [
- '\n\nSnippets (access as `snippets.KEY` in your code -- do NOT re-embed as string literals):',
- '```js',
- `const snippets = \n${JSON.stringify(verbatim, null, 2)}`,
- '```',
- ].join('\n')
- : '';
- const pendingBlock =
- pending.length > 0
- ? [
- '\n\nSnippets still being composed for you -- reference them as `snippets.KEY` exactly like the others; the finished text is injected when your code runs:',
- ...pending.map(([key, brief]) => `- \`snippets.${key}\` -- ${brief}`),
- ].join('\n')
- : '';
+ const requestBlock = request
+ ? `The user's request, for tone, intent, and any exact text it supplies — your assigned task below is your ONLY scope:\n<user_request>\n${request}\n</user_request>\n\n`
+ : '';
const contextBlock = `\n\nRelevant region of the document:\n<document>\n${context}\n</document>`;
- return `Carry out this edit task in full:\n${task}${snippetBlock}${pendingBlock}${contextBlock}`;
+ return `${requestBlock}Carry out this edit task in full:\n<task>\n${task}\n</task>${contextBlock}`;
}
diff --git a/js/ai-editing-worker/src/ai-editing/agents/coder.ts b/js/ai-editing-worker/src/ai-editing/agents/coder.ts
index a5a0c7fba2..d7e408bbce 100644
--- a/js/ai-editing-worker/src/ai-editing/agents/coder.ts
+++ b/js/ai-editing-worker/src/ai-editing/agents/coder.ts
@@ -29,13 +29,12 @@ export async function coder(
// Cap allows headroom for larger multi-part tasks and a few error retries.
stopWhen: [stepCountIs(7), hasToolCall('reportBlocked')],
system: CHILD_SYSTEM,
- prompt: buildPrompt(task, deps.context, deps.snippets),
+ prompt: buildPrompt(task, deps.context, deps.request),
tools: {
runCode: createRunCodeTool({
session: session,
doc: deps.doc,
awarenessSource: deps.awarenessSource,
- snippets: deps.snippets,
params: deps.params,
typingAnimations: deps.typingAnimations,
sleep: deps.sleep,
@@ -53,4 +52,3 @@ export async function coder(
abortSignal: deps.signal,
});
}
-
diff --git a/js/ai-editing-worker/src/ai-editing/agents/index.ts b/js/ai-editing-worker/src/ai-editing/agents/index.ts
index aeebe992ec..766898cef5 100644
--- a/js/ai-editing-worker/src/ai-editing/agents/index.ts
+++ b/js/ai-editing-worker/src/ai-editing/agents/index.ts
@@ -1,5 +1,4 @@
export { CHILD_SYSTEM, coder } from './coder';
export { interpreter } from './interpreter';
-export { snippet } from './snippet';
export { supervisor } from './supervisor';
export type { RunAgentOptions, RunTaskDeps } from './types';
diff --git a/js/ai-editing-worker/src/ai-editing/agents/snippet.ts b/js/ai-editing-worker/src/ai-editing/agents/snippet.ts
deleted file mode 100644
index 6ad827f3bd..0000000000
--- a/js/ai-editing-worker/src/ai-editing/agents/snippet.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { generateText, type LanguageModel } from 'ai';
-import SNIPPET from '../prompts/SNIPPET.md';
-import { EDIT_PROVIDER_OPTIONS } from './model-options';
-
-/** Compose one snippet of prose from a brief; the raw text is the result. */
-export async function snippet(
- brief: string,
- documentContext: string,
- model: LanguageModel,
- signal?: AbortSignal
-) {
- const result = await generateText({
- model,
- system: SNIPPET,
- prompt: `Brief: ${brief}\n\nRegion of the document your text will be inserted into:\n<document>\n${documentContext}\n</document>`,
- providerOptions: EDIT_PROVIDER_OPTIONS,
- abortSignal: signal,
- });
- return { text: result.text, totalUsage: result.totalUsage };
-}
diff --git a/js/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts b/js/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts
new file mode 100644
index 0000000000..9fa8543bb2
--- /dev/null
+++ b/js/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts
@@ -0,0 +1,171 @@
+import type {
+ LanguageModelV3StreamPart,
+ LanguageModelV3Usage,
+} from '@ai-sdk/provider';
+import { MockLanguageModelV3 } from 'ai/test';
+import { describe, expect, it } from 'vitest';
+import type { ResolvedModels } from '../../run-edit';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { mockAwarenessSource } from '../awareness/awareness-source';
+import { Doc } from '../doc/doc';
+import type { DispatchEditTrace } from '../tools';
+import { supervisor } from './supervisor';
+
+const usage: LanguageModelV3Usage = {
+ inputTokens: {
+ total: 10,
+ noCache: undefined,
+ cacheRead: undefined,
+ cacheWrite: undefined,
+ },
+ outputTokens: { total: 5, text: 5, reasoning: undefined },
+};
+
+const EDIT_1 = { editing_instruction: 'first edit: bold the paragraph' };
+const EDIT_2 = { editing_instruction: 'second edit: italicize the paragraph' };
+
+/** Supervisor step 1: two parallel dispatch calls. Pauses between them and
+ * awaits `onBetweenCalls` so the test can assert coder-1 started before
+ * call-2 is dispatched, then lets the stream proceed. */
+function dispatchStepStream(
+ onBetweenCalls: () => Promise<void>
+): ReadableStream<LanguageModelV3StreamPart> {
+ return new ReadableStream({
+ async start(controller) {
+ controller.enqueue({ type: 'stream-start', warnings: [] });
+ controller.enqueue({
+ type: 'tool-input-start',
+ id: 'call-1',
+ toolName: 'dispatch',
+ });
+ controller.enqueue({
+ type: 'tool-input-delta',
+ id: 'call-1',
+ delta: JSON.stringify(EDIT_1),
+ });
+ controller.enqueue({ type: 'tool-input-end', id: 'call-1' });
+ controller.enqueue({
+ type: 'tool-call',
+ toolCallId: 'call-1',
+ toolName: 'dispatch',
+ input: JSON.stringify(EDIT_1),
+ });
+ await onBetweenCalls();
+ controller.enqueue({
+ type: 'tool-input-start',
+ id: 'call-2',
+ toolName: 'dispatch',
+ });
+ controller.enqueue({
+ type: 'tool-input-delta',
+ id: 'call-2',
+ delta: JSON.stringify(EDIT_2),
+ });
+ controller.enqueue({ type: 'tool-input-end', id: 'call-2' });
+ controller.enqueue({
+ type: 'tool-call',
+ toolCallId: 'call-2',
+ toolName: 'dispatch',
+ input: JSON.stringify(EDIT_2),
+ });
+ controller.enqueue({
+ type: 'finish',
+ finishReason: { unified: 'tool-calls', raw: undefined },
+ usage,
+ });
+ controller.close();
+ },
+ });
+}
+
+/** Supervisor step 2: plain text wrap-up after the tool result. */
+function textStepStream(): ReadableStream<LanguageModelV3StreamPart> {
+ return new ReadableStream({
+ start(controller) {
+ controller.enqueue({ type: 'stream-start', warnings: [] });
+ controller.enqueue({ type: 'text-start', id: 't1' });
+ controller.enqueue({
+ type: 'text-delta',
+ id: 't1',
+ delta: 'All edits applied.',
+ });
+ controller.enqueue({ type: 'text-end', id: 't1' });
+ controller.enqueue({
+ type: 'finish',
+ finishReason: { unified: 'stop', raw: undefined },
+ usage,
+ });
+ controller.close();
+ },
+ });
+}
+
+describe('supervisor — streamed dispatch', () => {
+ it('launches coders from streaming args before the dispatch call completes', async () => {
+ const coderStartCount = { value: 0 };
+ const { promise: coder1Started, resolve: resolveCoder1 } =
+ Promise.withResolvers<void>();
+ let step = 0;
+ // Coders run against this; no tool calls, so each finishes in one step.
+ const codingModel = new MockLanguageModelV3({
+ modelId: 'coder-mock',
+ doGenerate: async () => {
+ coderStartCount.value++;
+ resolveCoder1();
+ return {
+ content: [{ type: 'text' as const, text: 'done' }],
+ finishReason: { unified: 'stop' as const, raw: undefined },
+ usage,
+ warnings: [],
+ };
+ },
+ });
+ const supervisorModel = new MockLanguageModelV3({
+ modelId: 'supervisor-mock',
+ doStream: async () => ({
+ stream:
+ step++ === 0
+ ? dispatchStepStream(async () => {
+ // coder1 should start and complete before the supervisor is done
+ await coder1Started;
+ expect(coderStartCount.value).toBe(1);
+ })
+ : textStepStream(),
+ }),
+ });
+ const models = {
+ supervisor: supervisorModel,
+ interpret: codingModel,
+ coding: codingModel,
+ snippet: codingModel,
+ snippetHigh: codingModel,
+ } as unknown as ResolvedModels;
+
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ const editTraces: DispatchEditTrace[] = [];
+
+ const result = await supervisor(session, 'make both edits', models, {
+ borrowWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ runner: () => [],
+ interpret: false,
+ sleep: async () => {},
+ onEditTrace: (edit) => editTraces.push(edit),
+ });
+
+ // Both coders ran exactly once (execute joined the onInputAvailable run).
+ expect(coderStartCount.value).toBe(2);
+
+ // The streamed launch is stamped into both traces.
+ expect(editTraces).toHaveLength(2);
+ expect(editTraces[0]!.streamedAt).toBeGreaterThan(0);
+ expect(editTraces[1]!.streamedAt).toBeGreaterThan(0);
+
+ expect(result.text).toBe('All edits applied.');
+ expect(result.steps).toHaveLength(2);
+ });
+});
diff --git a/js/ai-editing-worker/src/ai-editing/agents/supervisor.ts b/js/ai-editing-worker/src/ai-editing/agents/supervisor.ts
index 3a42976071..5cb78eed2e 100644
--- a/js/ai-editing-worker/src/ai-editing/agents/supervisor.ts
+++ b/js/ai-editing-worker/src/ai-editing/agents/supervisor.ts
@@ -1,4 +1,4 @@
-import { generateText, hasToolCall, stepCountIs } from 'ai';
+import { hasToolCall, stepCountIs, streamText } from 'ai';
import type { ResolvedModels } from '../../run-edit';
import type { LexicalSession } from '../ai-toolkit';
import API_COMPACT from '../prompts/API_COMPACT.md';
@@ -11,12 +11,14 @@ import { numberLines, serializeWithXml } from '../utils';
import { coder } from './coder';
import { interpreter } from './interpreter';
import { EDIT_PROVIDER_OPTIONS } from './model-options';
-import { snippet } from './snippet';
import type { RunAgentOptions } from './types';
export type { RunAgentOptions } from './types';
-const MASTER_SYSTEM = `${SHARED}\n${SUPERVISOR}\n${API_COMPACT}`;
+// TODO(wolf): figure out if we want this. Leaving it off for now.
+const USE_COMPACT = false;
+
+const MASTER_SYSTEM = `${SHARED}\n${SUPERVISOR}${USE_COMPACT ? `\n${API_COMPACT}` : ''}`;
const INTERPRET_SYSTEM = `${SHARED}\n${INTERPRET}`;
export async function supervisor(
@@ -50,30 +52,30 @@ export async function supervisor(
intent = interpretation.text;
}
+ const dispatch = createDispatchTool({
+ session,
+ childModel: models.coding,
+ tracker,
+ request: intent ? `${request}\n\n<intent>\n${intent}\n</intent>` : request,
+ params: opts.params,
+ typingAnimations: opts.typingAnimations,
+ sleep: opts.sleep,
+ signal: opts.signal,
+ makeWriter: opts.borrowWriter,
+ runTask: coder,
+ serialize,
+ runner: opts.runner,
+ onOps: opts.onOps,
+ onCoderResult: opts.onCoderResult,
+ onEditTrace: opts.onEditTrace,
+ });
+
const tools = {
reportBlocked: createImBlockedTool(
'Call this when you cannot proceed without more information or when the task is impossible.',
true
),
- dispatch: createDispatchTool({
- session,
- childModel: models.coding,
- snippetModel: models.snippet,
- snippetHighModel: models.snippetHigh,
- tracker,
- runSnippet: snippet,
- params: opts.params,
- typingAnimations: opts.typingAnimations,
- sleep: opts.sleep,
- signal: opts.signal,
- makeWriter: opts.borrowWriter,
- runTask: coder,
- serialize,
- runner: opts.runner,
- onOps: opts.onOps,
- onCoderResult: opts.onCoderResult,
- onEditTrace: opts.onEditTrace,
- }),
+ dispatch: dispatch.tool,
};
const intentBlock = intent ? `<intent>\n${intent}\n</intent>\n\n` : '';
@@ -84,7 +86,7 @@ export async function supervisor(
// enough.
const stepDurationsMs: number[] = [];
let lastStepAt = Date.now();
- const result = await generateText({
+ const result = streamText({
model: models.supervisor,
stopWhen: [stepCountIs(7), hasToolCall('reportBlocked')],
system: MASTER_SYSTEM,
@@ -92,24 +94,39 @@ export async function supervisor(
tools,
providerOptions: EDIT_PROVIDER_OPTIONS,
abortSignal: opts.signal,
+ prepareStep: ({ stepNumber }) =>
+ // require that the very first thing it does is a tool call
+ stepNumber === 0 ? { toolChoice: 'required' } : undefined,
onStepFinish: () => {
const now = Date.now();
stepDurationsMs.push(now - lastStepAt);
lastStepAt = now;
},
});
- tracker.add(models.supervisor as { modelId: string }, result.totalUsage);
- const blocked = result.steps
+ for await (const part of result.fullStream) {
+ if (part.type === 'error') throw part.error;
+ if (part.type === 'abort')
+ throw opts.signal?.reason ?? new Error('edit session aborted');
+ }
+
+ const [steps, totalUsage, text] = await Promise.all([
+ result.steps,
+ result.totalUsage,
+ result.text,
+ ]);
+ tracker.add(models.supervisor as { modelId: string }, totalUsage);
+
+ const blocked = steps
.flatMap((s) => s.toolCalls)
.find((c) => c.toolName === 'reportBlocked');
const clarification = (blocked?.input as { message: string } | undefined)
?.message;
return {
- text: result.text || 'Applied edits.',
+ text: text || 'Applied edits.',
totalUsage: tracker,
- steps: result.steps,
+ steps,
stepDurationsMs,
intent,
interpretDurationMs,
diff --git a/js/ai-editing-worker/src/ai-editing/agents/types.ts b/js/ai-editing-worker/src/ai-editing/agents/types.ts
index 672edd23a4..6eede290a7 100644
--- a/js/ai-editing-worker/src/ai-editing/agents/types.ts
+++ b/js/ai-editing-worker/src/ai-editing/agents/types.ts
@@ -2,8 +2,8 @@ import type { AwarenessSource } from '../awareness';
import type { Doc } from '../doc';
import type { DocumentOp } from '../editor';
import type { DocumentOpQueueParams } from '../queue';
-import type { SnippetSource } from '../runtime';
import type {
+ CoderRunCode,
DispatchEditTrace,
RunCodeToolOptions,
Writer,
@@ -14,7 +14,9 @@ export type RunTaskDeps = {
awarenessSource: AwarenessSource;
runner: RunCodeToolOptions['runner'];
context: string;
- snippets?: SnippetSource;
+ /** The user's original edit request (plus resolved intent when available),
+ * tone and content context for the writer. */
+ request?: string;
params?: DocumentOpQueueParams;
typingAnimations?: boolean;
sleep?: (ms: number) => Promise<void>;
@@ -33,6 +35,6 @@ export type RunAgentOptions = {
sleep?: (ms: number) => Promise<void>;
signal?: AbortSignal;
onOps?: (ops: DocumentOp[]) => void;
- onCoderResult?: (codes: string[][]) => void;
- onEditTrace?: (edits: DispatchEditTrace[]) => void;
+ onCoderResult?: (codes: CoderRunCode[]) => void;
+ onEditTrace?: (edit: DispatchEditTrace) => void;
};
diff --git a/js/ai-editing-worker/src/ai-editing/ai-toolkit/modify.test.ts b/js/ai-editing-worker/src/ai-editing/ai-toolkit/modify.test.ts
index 7505420e38..493a2d8104 100644
--- a/js/ai-editing-worker/src/ai-editing/ai-toolkit/modify.test.ts
+++ b/js/ai-editing-worker/src/ai-editing/ai-toolkit/modify.test.ts
@@ -13,7 +13,7 @@ import { $modifyNode } from './modify';
import { createEditingSession, loadMarkdown } from './session';
describe('$modifyNode', () => {
- it("op 'blockType' changes type + level, minting a fresh id the old id forwards to", () => {
+ it("op 'blockType' changes type + level, versioning the id the old id forwards to", () => {
const { session, ids } = setup('Notes');
const old = ids[0]!;
edit(session, () =>
@@ -25,9 +25,38 @@ describe('$modifyNode', () => {
const xml = serializeWithXml(session);
expect(xml).toContain('<h2');
expect(xml).toContain('Notes');
- // fresh id replaces the old one, but the old id still resolves to the node
+ // the new id is the old id suffixed `~v1` -- recognizable but distinct
+ expect(xml).toContain(`id="${old}~v1"`);
expect(xml).not.toContain(`id="${old}"`);
- expect(read(session, () => $getId($byId(session, old)))).not.toBe(old);
+ // both the versioned id and the original still resolve to the node
+ expect(read(session, () => $getId($byId(session, `${old}~v1`)))).toBe(
+ `${old}~v1`
+ );
+ expect(read(session, () => $getId($byId(session, old)))).toBe(`${old}~v1`);
+ });
+
+ it("op 'blockType' bumps the version on each successive retype", () => {
+ const { session, ids } = setup('Notes');
+ const old = ids[0]!;
+ edit(session, () =>
+ $modifyNode(session, old, {
+ op: 'blockType',
+ block: { type: 'heading', level: 2 },
+ })
+ );
+ edit(session, () =>
+ $modifyNode(session, `${old}~v1`, {
+ op: 'blockType',
+ block: { type: 'quote' },
+ })
+ );
+ const xml = serializeWithXml(session);
+ expect(xml).toContain('<blockquote');
+ expect(xml).toContain(`id="${old}~v2"`);
+ // every prior handle still points at the current node
+ for (const id of [old, `${old}~v1`, `${old}~v2`]) {
+ expect(read(session, () => $getId($byId(session, id)))).toBe(`${old}~v2`);
+ }
});
it("op 'text' rewrites a block's content, keeping type + id", () => {
diff --git a/js/ai-editing-worker/src/ai-editing/ai-toolkit/session.ts b/js/ai-editing-worker/src/ai-editing/ai-toolkit/session.ts
index 39711ae846..b266d5e2d1 100644
--- a/js/ai-editing-worker/src/ai-editing/ai-toolkit/session.ts
+++ b/js/ai-editing-worker/src/ai-editing/ai-toolkit/session.ts
@@ -13,6 +13,8 @@ import {
SupportedNodeTypes,
} from '../../../../lexical-core/node-list';
import {
+ $getId,
+ $setId,
$updateAllNodeIds,
type NodeIdMappings,
nodeIdPlugin,
@@ -94,13 +96,24 @@ export function toSnapshot(session: LexicalSession): SerializedEditorState {
return session.editor.getEditorState().toJSON();
}
+/** Derive the retype id for a node: `b3` -> `b3~v1` -> `b3~v2`. The stem stays
+ * stable so the agent can see a retyped node is the same logical block, while
+ * the id still changes (required — see `$retypeContainer`). `~` is outside
+ * nanoid's alphabet, so a fresh random id can never be mistaken for a version. */
+function nextVersionId(id: string): string {
+ const m = /^(.*)~v(\d+)$/.exec(id);
+ return m ? `${m[1]}~v${Number(m[2]) + 1}` : `${id}~v1`;
+}
+
/**
* Retype a container node by swapping in a freshly-built replacement. The
* replacement gets a FRESH durable id (Loro can't reshape a container in place —
* reusing the id makes the change vanish on sync, a fresh id reads as a clean
- * delete + insert), and every id that pointed at the old node is forwarded to
- * the replacement. Children carry over via `replace(…, true)` with their own ids
- * intact. Backs `$setBlockType` and `$setListType`.
+ * delete + insert). The new id is the old id with a `~vN` suffix so it stays
+ * recognizable to the agent (`b3` -> `b3~v1`), and every id that pointed at the
+ * old node is forwarded to the replacement so prior handles keep resolving.
+ * Children carry over via `replace(…, true)` with their own ids intact. Backs
+ * `$setBlockType` and `$setListType`.
*
* This is specifically for retyping containers — NOT a generic node replace.
* Inline wraps (`$wrapInBlock`) re-parent a node without minting a fresh id.
@@ -111,7 +124,11 @@ export function $retypeContainer<T extends ElementNode>(
replacement: T
): T {
const oldKey = node.getKey();
+ const oldId = $getId(node);
node.replace(replacement, true);
+ // Stamp the versioned id BEFORE the walk so `$assertId` adopts it instead of
+ // minting a random one.
+ if (oldId) $setId(replacement, nextVersionId(oldId));
$updateAllNodeIds(session.ids, replacement);
const { idToNodeKeyMap } = session.ids;
const newKey = replacement.getKey();
diff --git a/js/ai-editing-worker/src/ai-editing/prompts/API_COMPACT.md b/js/ai-editing-worker/src/ai-editing/prompts/API_COMPACT.md
index 5d12876763..ddeae3ee70 100644
--- a/js/ai-editing-worker/src/ai-editing/prompts/API_COMPACT.md
+++ b/js/ai-editing-worker/src/ai-editing/prompts/API_COMPACT.md
@@ -15,6 +15,7 @@ The writer has the complete API reference. Use this compact list to help yoursel
- `convertToParagraph`, `convertToHeading`, `convertToQuote`, `convertToCodeBlock(id, language)`, `setLanguage(id, language)`
- Code block language is required. Use `setLanguage(id, language)` to change an existing code block's language.
+- A type conversion gives the block a fresh id: the old id + `~vN` suffix (`b1` → `b1~v1`). Same block; use the latest id going forward.
## Lists
diff --git a/js/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md b/js/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md
index e1b0c6448e..4983ee226a 100644
--- a/js/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md
+++ b/js/ai-editing-worker/src/ai-editing/prompts/API_COMPLETE.md
@@ -142,13 +142,15 @@ After:
```xml
<doc>
- <h2 id="b1"><t id="t1">Title</t></h2>
- <blockquote id="b2"><t id="t2">A quote</t></blockquote>
- <custom-code id="b3" direction="null" format="" indent="0" version="1" language="python"><t id="t3">code here</t></custom-code>
- <p id="b4"><t id="t4">Back to paragraph</t></p>
+ <h2 id="b1~v1"><t id="t1">Title</t></h2>
+ <blockquote id="b2~v1"><t id="t2">A quote</t></blockquote>
+ <custom-code id="b3~v1" direction="null" format="" indent="0" version="1" language="python"><t id="t3">code here</t></custom-code>
+ <p id="b4~v1"><t id="t4">Back to paragraph</t></p>
</doc>
```
+Converting a block's type gives it a fresh id: the old id with a `~vN` suffix (`b1` → `b1~v1`, again → `b1~v2`). It's the SAME block — the suffix just marks the retype, and the stem tells you which block it was. Both the suffixed id and the original resolve later in the same code, but going forward use the id shown in the latest XML.
+
## Lists
- `bulletList(idOrIds)` · `numberedList(idOrIds)` · `checklist(idOrIds)` · `setListType(id, kind)`
diff --git a/js/ai-editing-worker/src/ai-editing/prompts/CODER.md b/js/ai-editing-worker/src/ai-editing/prompts/CODER.md
index 8e046b323e..700a1da9d4 100644
--- a/js/ai-editing-worker/src/ai-editing/prompts/CODER.md
+++ b/js/ai-editing-worker/src/ai-editing/prompts/CODER.md
@@ -1,8 +1,8 @@
# Role: Coder
-You are the coder.
+You are the coder — one writer on a team carrying out a user's request to edit a document.
-You carry out one task from a supervisor by writing plain JavaScript against a single object, `editor`, then replying with a one-line summary. Your job is mechanical: translate the instruction into `editor` calls exactly.
+You carry out one task from a supervisor by writing plain JavaScript against a single object, `editor`, then replying with a one-line summary. Your prompt includes the user's original request: use it for tone, intent, and any exact text it supplies when your task asks you to compose — but it is NOT your task list. Your assigned task is your only scope; never edit outside it.
The task may be a single small change or a larger set of related changes confined to one region of the document -- either way, you MUST carry out the **whole** instruction before you summarize. Drive as many `editor` calls as the task needs (a loop, or several calls in one `runCode`); you don't have to stop after one change.
@@ -10,7 +10,7 @@ You do not see the whole document by default -- only a line-numbered XML window
## How you write edits
-You call `runCode(code)` with plain JS statements. The only things in scope are `editor` and (when provided) `snippets`. No `$`-helpers, no imports, no `s`, no `$getRoot`. For example:
+You call `runCode(code, snippets?)` with plain JS statements. The only things in scope are `editor` and `snippets`. No `$`-helpers, no imports, no `s`, no `$getRoot`. For example:
```js
editor.convertToHeading('b14', 2);
@@ -35,7 +35,7 @@ editor.bold('b5', 'Bluejay');
When you do need `insertLineBreak`, the `at` offset counts only characters (inline objects don't count). Append each line with `insertTextAfterInline(brRef, text)` and accumulate the running text length manually.
- Pass **plain text only** -- you MUST NOT ever use XML/markdown syntax. `editor.setText(id, '# x')` inserts the literal characters `# x`, it does not make a heading. We do not support or understand Markdown or XML in our editor.
- **`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.**
-- When the task provides a **`snippets` object**, use `snippets.KEY` directly rather than re-embedding its value as a string literal -- `editor.setText(id, snippets.code)`. This avoids escaping errors on special characters.
+- **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`; quotes and apostrophes break the script. This applies both to text you compose and to exact text from the task or user request, which you must copy character-for-character into your `snippets` values.
- 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.
- 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.
diff --git a/js/ai-editing-worker/src/ai-editing/prompts/SHARED.md b/js/ai-editing-worker/src/ai-editing/prompts/SHARED.md
index 10c897cb6b..eb4bbbe8bd 100644
--- a/js/ai-editing-worker/src/ai-editing/prompts/SHARED.md
+++ b/js/ai-editing-worker/src/ai-editing/prompts/SHARED.md
@@ -3,12 +3,12 @@
You are one role in a two-role editing system for handling user requests to edit a document:
- **Supervisor** -- turns the user's request into small, mechanical edit instructions and dispatches them to writers in rounds, reviewing the resulting diff after each round until the request is done.
-- **Writer** -- receives ONE mechanical edit instruction and carries it out by running JavaScript node-manipulation snippets against the document, then reports back.
+- **Writer** -- receives ONE mechanical edit instruction and carries it out by running mechanical document edits.
Shared ground rules for both roles:
-- The document is shown to you as **XML, which is a read-only structural *view*** -- the user sees the actual rendered rich text in their editor. The XML is never written back. All changes happen exclusively through node-manipulation API calls (`$`-helpers) addressed by node id.
-- The XML shows the document's typed AST: block nodes (`<p>`, `<h1>`–`<h6>`, `<blockquote>`, `<custom-code>`, `<ul>`, `<li>`, `<table>`, etc.) each with an `id` attribute; inline text runs as `<t id="...">` with format attributes (`bold="true"`, `italic="true"`, `underline="true"`, `strikethrough="true"`, `code="true"`).
+- The document is shown to you as **a read-only structural XML *view*** -- the user sees the actual rendered rich text in their editor. The XML is never written back..
+- The XML shows the document's tree: block nodes (`<p>`, `<h1>`–`<h6>`, `<blockquote>`, `<custom-code>`, `<ul>`, `<li>`, `<table>`, etc.) each with an `id` attribute; inline text runs as `<t id="...">` with format attributes (`bold="true"`, `italic="true"`, `underline="true"`, `strikethrough="true"`, `code="true"`).
- Address any node by its `id` attribute from the XML.
- Edits within a single dispatched batch run **in parallel** against one shared document, so only independent, non-conflicting edits may be batched together.
diff --git a/js/ai-editing-worker/src/ai-editing/prompts/SNIPPET.md b/js/ai-editing-worker/src/ai-editing/prompts/SNIPPET.md
deleted file mode 100644
index fc7430f0ab..0000000000
--- a/js/ai-editing-worker/src/ai-editing/prompts/SNIPPET.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# Role: Snippet Writer
-
-You compose one piece of text to be inserted into a document. You receive a brief describing what to write and the region of the document it will land in.
-
-- Your entire response is the snippet, verbatim. No preamble, no commentary, no quotes around it.
-- Write **plain text only** — no Markdown or XML syntax. `# x` inserts the literal characters `# x`; it does not make a heading. Structure (headings, lists, formatting) is someone else's job.
-- Follow the brief's shape and length exactly. "One paragraph" means one paragraph.
-- Match the tone and vocabulary of the surrounding document unless the brief says otherwise.
-- If the brief mentions sibling sections or an outline, stay in your lane: cover your piece, don't restate theirs.
diff --git a/js/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md b/js/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md
index 3b671ce71b..a236c6607a 100644
--- a/js/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md
+++ b/js/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md
@@ -2,26 +2,26 @@
You are the supervisor.
-Use the `<intent>` block as the resolved task. Apply it by calling `dispatch`. Stop once the latest dispatch result is good enough and give a one-line summary. Aim to complete the task in as few dispatch rounds as possible — ideally one or two. Plan thoroughly before dispatching so you don't need correction rounds.
+You are given a user request to edit a document, and will coordinate the dispatch of writers on our team to actually modify the document.
+
+You should aim to complete the task in few dispatch rounds, and should plan carefully so that you don't need to do many rounds of correction. As you type out your dispatch tool calls they will happen, so typing out a shorter initial writer dispatch quickly is good for UX.
+
+**Do not write any text before your first tool call.** Your very first output token must be a tool call — not a plan, not an acknowledgment. Think inside your instructions, not as preamble text.
## Dispatch Rules
- Each edit is one coherent writer task.
-- One region = one writer. Do NOT split a paragraph, list, table, or section across parallel writers.
-- Batch only clearly disjoint regions. If unsure, dispatch sequentially.
+- One region = one writer. Do NOT split a paragraph, list, table, or section across parallel writers. Don't dispatch two edits where the second edit depends on nodes created by the first edit.
+- Call dispatch multiple times in parallel for clearly disjoint regions. If unsure, dispatch sequentially.
- A writer can perform many related changes in one instruction.
-- **Never batch sequentially-dependent insertions in a single dispatch.** If edit B inserts after a node created by edit A, you don't yet know that node's id -- dispatch A first, get the result, then dispatch B using the id from the result. Batching them will BLOCK edit B every time. Use concurrency where you can, but be VERY careful and THINK about this.
## Instructions
-- Mention existing XML ids for the target region; dispatch expands context from those ids.
-- Default to `snippet_specs` for any content you must compose — new sections, paragraphs, rewrites, or any text you would otherwise write yourself: key -> a brief saying what to write, the tone, and the expected shape/length (e.g. "one paragraph, ~4 sentences"). When several specs cover sibling sections, repeat the shared outline in each brief and say how they relate, so they don't overlap or drift in tone.
-- A spec is a plain brief string, or `{ "brief": ..., "effort": "high" }`. Default effort is low; use the string form. Set `effort: "high"` only when the writing quality is itself the deliverable: long-form prose the reader will dwell on, creative writing, persuasive copy. Keep low effort for headings, captions, list items, short factual text, and filler. When unsure, use low.
-- Use `snippets` (verbatim text) only when the text must be exact — ids, user-supplied text, quotes, code, values, special characters, anything you must control character-for-character — or when the brief would be longer than the text itself (a short word or phrase). Refer to it as `snippets.KEY` in the instruction rather than embedding it.
-- Never ask the writer itself to invent or compose content -- writers are mechanical appliers. Content reaches them through snippets, whether verbatim or spec-composed.
-- Use native editor objects when appropriate: divider, table, heading, quote, code block, image, video, equation, date, mention, document-card. Do not simulate native objects with plain text, like `======` for a divider.
-- To mention a person, use the `userId`/`email` (or `contactId`/`name`/`emailOrDomain`) from the request. To add a document-card, use the `documentId`/`documentName`/`blockName` from the request. Pass these to the writer via `snippets.KEY`. Never invent or look up these ids -- they come from the request.
-- Do not write literal XML/Markdown unless the user wants those characters.
+You should provide high level English instructions to writers about the changes you want different writers to do. For example, "move paragraph Mz5qcIFm to be right above the q3IMz52m heading." Our writers are non technical and can't understand Markdown or coding terms. Try to avoid telling them *how* to do things. Figuring out how to make changes to documents what they are trained to do.
+
+- Mention existing XML ids for the target region. The writers only get to see context surrounding mentioned nodes.
+- Use native editor objects when appropriate, like dividers, tables, etc. Do not simulate native objects with plain text, like `======` for a divider.
+- To mention a person, use the `userId`/`email` (or `contactId`/`name`/`emailOrDomain`) from the request. To add a document-card, use the `documentId`/`documentName`/`blockName` from the request. Do not write literal XML/Markdown unless the user wants those literal characters.
- Do not invent or preserve ids. New ids are assigned automatically and existing ids may change.
- Do not write code yourself; describe the change mechanically.
- Do not try to inject formatting like bullet unicode into your snippets. Let the writer handle the formatting.
@@ -29,14 +29,11 @@ Use the `<intent>` block as the resolved task. Apply it by calling `dispatch`. S
## After Dispatch
-- If the document feels right, meets the interpreter criteria, isn't weird, and you're happy, you can finish.
-- If blocked, failed, or wrong, dispatch a clearer correction using current ids from the latest result.
-- Prefer in-place corrections. Don't remove-and-recreate a structure you already built -- patch the existing nodes. Recreating churns ids and rarely converges.
-- If the same region is still wrong after 2 correction rounds, try a fundamentally different approach — different op, different structure — rather than repeating variations of the same dispatch.
-- If it is still wrong after a third attempt, **give up on that region**: leave it as-is, note it in your final summary, and move on. Do not spend more rounds on something the writer cannot resolve.
-- Judge by content and structure, not id stability.
-- It is up to you to determine when we are "done" and the result is satisfactory; don't go on forever. Also don't make changes that undo all of your hard work if it's mostly done.
-- Ensure that the formatting of the final document is good, doesn't overload formatting or use weird whitespace.
+If the document meets the users request you are done. Otherwise dispatch an additional round to finish the changes that have to get done. You are the sole person who can end the flow so don't let us run forever.
+
+- Try to avoid re-doing work you've done. If it's good enough keep it.
+- If the writers keep on getting it wrong over and over then just give up.
+- Ensure that the formatting of the final document is correct and doesn't overload formatting or use weird whitespace.
- Unrelated changes could crop up since other users might have edited the doc. Ensure just that your changes made it as expected.
## When You Cannot Proceed
diff --git a/js/ai-editing-worker/src/ai-editing/runtime.test.ts b/js/ai-editing-worker/src/ai-editing/runtime.test.ts
index 591b3f24f5..25688b5fc3 100644
--- a/js/ai-editing-worker/src/ai-editing/runtime.test.ts
+++ b/js/ai-editing-worker/src/ai-editing/runtime.test.ts
@@ -8,7 +8,7 @@ import {
type CodeRunner,
docIds,
runEditorCode,
- type SnippetSource,
+ snippetKeysIn,
} from './runtime';
// In-process executor for unit tests: the QuickJS sandbox's wasm import doesn't
@@ -46,7 +46,7 @@ function topIds(session: LexicalSession): string[] {
async function runCode(
session: LexicalSession,
code: string,
- snippets?: SnippetSource
+ snippets?: Record<string, string>
): Promise<string> {
return runEditorCode({
session,
@@ -110,54 +110,48 @@ describe('runtime — end to end against real Lexical', () => {
});
});
-describe('runtime — snippet settling', () => {
- it('resolves pending snippets before the code runs', async () => {
+describe('runtime — writer-authored snippets', () => {
+ it('injects call snippets into the code scope', async () => {
const { session, ids } = build('first');
const summary = await runCode(
session,
`editor.insertParagraphAfter('${ids[0]}', snippets.intro);`,
- {
- intro: {
- brief: 'one line',
- promise: new Promise((resolve) =>
- setTimeout(() => resolve('composed later'), 5)
- ),
- },
- }
+ { intro: 'writer wrote this' }
);
expect(summary).toBe('ok');
- expect(serializeWithXml(session)).toContain('composed later');
+ expect(serializeWithXml(session)).toContain('writer wrote this');
});
- it('mixes verbatim strings and pending snippets', async () => {
- const { session, ids } = build('first');
+ it('fails clearly when the code references an unprovided key', async () => {
+ const { session, ids } = build('untouched');
+ const before = serializeWithXml(session);
const summary = await runCode(
session,
- `editor.insertParagraphAfter('${ids[0]}', snippets.a + ' ' + snippets.b);`,
- {
- a: 'verbatim',
- b: { brief: 'x', promise: Promise.resolve('pending') },
- }
+ `editor.insertParagraphAfter('${ids[0]}', snippets.ghost);`,
+ { other: 'x' }
);
- expect(summary).toBe('ok');
- expect(serializeWithXml(session)).toContain('verbatim pending');
+ expect(summary).toMatch(/error: snippet "ghost" is not defined/);
+ expect(serializeWithXml(session)).toBe(before);
});
- it('reports a failed snippet by key and applies nothing', async () => {
+ it('fails clearly when code references snippets but none were passed', async () => {
const { session, ids } = build('untouched');
- const before = serializeWithXml(session);
const summary = await runCode(
session,
- `editor.insertParagraphAfter('${ids[0]}', snippets.bad);`,
- {
- bad: {
- brief: 'x',
- promise: Promise.reject(new Error('model unavailable')),
- },
- }
+ `editor.insertParagraphAfter('${ids[0]}', snippets.x);`
);
- expect(summary).toBe('error: snippet "bad" failed: model unavailable');
- expect(serializeWithXml(session)).toBe(before);
+ expect(summary).toMatch(/error: snippet "x" is not defined/);
+ });
+});
+
+describe('snippetKeysIn', () => {
+ it('extracts dot and bracket key references from code', () => {
+ const code = `
+ editor.setText(id, snippets.alpha);
+ const x = snippets["with-dash"] + snippets.alpha;
+ editor.bold(id, snippets['beta']);
+ `;
+ expect(snippetKeysIn(code).sort()).toEqual(['alpha', 'beta', 'with-dash']);
});
});
diff --git a/js/ai-editing-worker/src/ai-editing/runtime.ts b/js/ai-editing-worker/src/ai-editing/runtime.ts
index 70c06d1f3c..199f166d11 100644
--- a/js/ai-editing-worker/src/ai-editing/runtime.ts
+++ b/js/ai-editing-worker/src/ai-editing/runtime.ts
@@ -33,51 +33,15 @@ export type CodeRunner = (
snippets?: Record<string, string>
) => DocumentOp[] | Promise<DocumentOp[]>;
-/** How much a snippet writer invests in a composed snippet: `low` uses the
- * fast default model, `high` routes to the stronger composition model. */
-export type PendingSnippetEffort = 'low' | 'high';
-
-/** A snippet still being composed by a snippet agent: `brief` describes it to
- * the coder's prompt; `promise` resolves to the final text. */
-export type PendingSnippet = { brief: string; promise: Promise<string> };
-
-/** A static snippet is already-available text. */
-export type StaticSnippet = string;
-
-/** Snippet values as the coder sees them: verbatim strings plus pending ones.
- * Settled into plain strings before any code runs — promises never cross the
- * `CodeRunner` boundary. */
-export type SnippetSource = Record<string, StaticSnippet | PendingSnippet>;
-
-export function isStaticSnippet(
- value: StaticSnippet | PendingSnippet
-): value is StaticSnippet {
- return typeof value === 'string';
-}
-
-export function isPendingSnippet(
- value: StaticSnippet | PendingSnippet
-): value is PendingSnippet {
- return !isStaticSnippet(value);
-}
-
-/** Await every pending snippet, naming the key in any failure. */
-export async function settleSnippets(
- source?: SnippetSource
-): Promise<Record<string, StaticSnippet> | undefined> {
- if (!source) return undefined;
- const entries = await Promise.all(
- Object.entries(source).map(async ([key, value]) => {
- if (isStaticSnippet(value)) return [key, value] as const;
- try {
- return [key, await value.promise] as const;
- } catch (e) {
- const message = e instanceof Error ? e.message : String(e);
- throw new Error(`snippet "${key}" failed: ${message}`);
- }
- })
- );
- return Object.fromEntries(entries);
+/** Keys the generated code references as `snippets.KEY` / `snippets["KEY"]`. */
+export function snippetKeysIn(code: string): string[] {
+ const keys = new Set<string>();
+ for (const match of code.matchAll(
+ /\bsnippets\s*(?:\.\s*([A-Za-z_$][\w$]*)|\[\s*["']([^"']+)["']\s*\])/g
+ )) {
+ keys.add((match[1] ?? match[2])!);
+ }
+ return [...keys];
}
export type RunEditorCodeArgs = {
@@ -86,7 +50,9 @@ export type RunEditorCodeArgs = {
code: string;
awarenessSource: AwarenessSource;
runner: CodeRunner;
- snippets?: SnippetSource;
+ /** Content the writer composed for this call, passed alongside its code and
+ * referenced there as `snippets.KEY`. */
+ snippets?: Record<string, string>;
params?: DocumentOpQueueParams;
sleep?: (ms: number) => Promise<void>;
/** Skip animation entirely -- apply each op directly with no typing, pauses, or cursor movement. */
@@ -103,8 +69,18 @@ export type RunEditorCodeArgs = {
export async function runEditorCode(args: RunEditorCodeArgs): Promise<string> {
let ops: DocumentOp[];
try {
- const snippets = await settleSnippets(args.snippets);
- ops = await args.runner(docIds(args.session), args.code, snippets);
+ // Every key the code references must come with the call — catch a missing
+ // one here with a pointed message instead of an undefined leaking into ops.
+ const missing = snippetKeysIn(args.code).filter(
+ (key) => args.snippets?.[key] === undefined
+ );
+ if (missing.length > 0) {
+ const list = missing.map((k) => `"${k}"`).join(', ');
+ throw new Error(
+ `snippet${missing.length > 1 ? 's' : ''} ${list} ${missing.length > 1 ? 'are' : 'is'} not defined -- pass their text in the \`snippets\` argument of this runCode call`
+ );
+ }
+ ops = await args.runner(docIds(args.session), args.code, args.snippets);
} catch (e) {
if (!(e instanceof Error)) throw new Error(String(e));
return `error: ${e.message}`;
diff --git a/js/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts b/js/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts
index 868ad42f0f..5ccd915ea2 100644
--- a/js/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts
+++ b/js/ai-editing-worker/src/ai-editing/tools/dispatch.test.ts
@@ -1,11 +1,9 @@
import type { LanguageModel, LanguageModelUsage } from 'ai';
import { describe, expect, it } from 'vitest';
import type { coder } from '../agents';
-import type { snippet } from '../agents/snippet';
import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
import { mockAwarenessSource } from '../awareness/awareness-source';
import { Doc } from '../doc/doc';
-import { type SnippetSource, settleSnippets } from '../runtime';
import { TokenTracker } from '../token-tracker';
import {
computeContextRange,
@@ -115,173 +113,113 @@ describe('computeContextRange', () => {
});
});
-describe('dispatch — snippet_specs', () => {
- const usage: LanguageModelUsage = {
- inputTokens: 10,
- outputTokens: 5,
- totalTokens: 15,
- inputTokenDetails: {
- noCacheTokens: undefined,
- cacheReadTokens: undefined,
- cacheWriteTokens: undefined,
+const usage: LanguageModelUsage = {
+ inputTokens: 10,
+ outputTokens: 5,
+ totalTokens: 15,
+ inputTokenDetails: {
+ noCacheTokens: undefined,
+ cacheReadTokens: undefined,
+ cacheWriteTokens: undefined,
+ },
+ outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
+};
+const childModel = { modelId: 'child-model' } as unknown as LanguageModel;
+const coderResult = (async () =>
+ ({ totalUsage: usage, steps: [] }) as unknown as Awaited<
+ ReturnType<typeof coder>
+ >)();
+
+function setup() {
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ const tracker = new TokenTracker();
+ const editTraces: DispatchEditTrace[] = [];
+ const tasks: string[] = [];
+ // The request each coder received, to verify it reaches every writer.
+ const requests: Array<string | undefined> = [];
+ const dispatch = createDispatchTool({
+ session,
+ childModel,
+ tracker,
+ request: 'make it formal',
+ runner: () => [],
+ makeWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ runTask: async (_session, task, _model, deps) => {
+ tasks.push(task);
+ requests.push(deps.request);
+ deps.onRunCode?.();
+ return coderResult;
},
- outputTokenDetails: { textTokens: undefined, reasoningTokens: undefined },
- };
- const snippetModel = { modelId: 'snip-model' } as unknown as LanguageModel;
- const snippetHighModel = {
- modelId: 'snip-high-model',
- } as unknown as LanguageModel;
- const childModel = { modelId: 'child-model' } as unknown as LanguageModel;
- const coderResult = (async () =>
- ({ totalUsage: usage, steps: [] }) as unknown as Awaited<
- ReturnType<typeof coder>
- >)();
-
- function setup(opts: {
- runSnippet: typeof snippet;
- onSnippets?: (s: SnippetSource | undefined) => void;
- }) {
- const session = createEditingSession();
- loadMarkdown(session, 'hello world');
- const tracker = new TokenTracker();
- const editTraces: DispatchEditTrace[][] = [];
- const dispatchTool = createDispatchTool({
- session,
- childModel,
- snippetModel,
- snippetHighModel,
- tracker,
- runSnippet: opts.runSnippet,
- runner: () => [],
- makeWriter: async () => ({
- doc: new Doc(session),
- awarenessSource: mockAwarenessSource(),
- release: () => {},
- }),
- runTask: async (_session, _task, _model, deps) => {
- opts.onSnippets?.(deps.snippets);
- deps.onRunCode?.();
- return coderResult;
- },
- onEditTrace: (edits) => editTraces.push(edits),
- });
- return { dispatchTool, tracker, editTraces };
- }
+ onEditTrace: (edit) => editTraces.push(edit),
+ });
+ return { ...dispatch, tracker, editTraces, tasks, requests };
+}
- const callOptions = { toolCallId: 't1', messages: [] };
+const callOptions = { toolCallId: 't1', messages: [] };
- it('launches one agent per spec, merges pending values, and tracks usage', async () => {
- const briefs: string[] = [];
- let seen: SnippetSource | undefined;
- const { dispatchTool, tracker, editTraces } = setup({
- runSnippet: async (brief) => {
- briefs.push(brief);
- return { text: `composed: ${brief}`, totalUsage: usage };
- },
- onSnippets: (s) => {
- seen = s;
- },
- });
- await dispatchTool.execute?.(
- {
- edits: [
- {
- editing_instruction: 'insert snippets.intro after the paragraph',
- snippets: { exact: 'as-is' },
- snippet_specs: { intro: 'one paragraph about intros' },
- },
- ],
- },
+describe('dispatch -- writer inputs', () => {
+ it('passes the user request to the writer', async () => {
+ const { tool, requests } = setup();
+ const out = await tool.execute?.(
+ { editing_instruction: 'first edit' },
callOptions
);
- expect(briefs).toEqual(['one paragraph about intros']);
- expect(await settleSnippets(seen)).toEqual({
- exact: 'as-is',
- intro: 'composed: one paragraph about intros',
- });
- expect(tracker.toEntries()).toContainEqual({
- model: 'snip-model',
- inputTokens: 10,
- outputTokens: 5,
- });
+ expect(out).toContain('✓ APPLIED');
+ expect(requests).toEqual(['make it formal']);
+ });
- expect(editTraces).toHaveLength(1);
- const [trace] = editTraces[0]!;
- expect(trace!.snippets).toMatchObject([
- {
- key: 'intro',
- brief: 'one paragraph about intros',
- text: 'composed: one paragraph about intros',
- },
- ]);
- expect(trace!.snippets[0]!.resolvedAt).toBeGreaterThanOrEqual(
- trace!.snippets[0]!.startedAt
+ it('records runCode timing in the trace', async () => {
+ const { tool, editTraces } = setup();
+ await tool.execute?.(
+ { editing_instruction: 'one edit' },
+ callOptions
);
- expect(trace!.runCodeAt).toHaveLength(1);
- expect(trace!.runCodeAt[0]).toBeGreaterThanOrEqual(trace!.coderStartedAt);
- expect(trace!.coderFinishedAt).toBeGreaterThanOrEqual(trace!.runCodeAt[0]!);
+ const trace = editTraces[0]!;
+ expect(trace.runCodeAt).toHaveLength(1);
+ expect(trace.runCodeAt[0]).toBeGreaterThanOrEqual(trace.coderStartedAt);
+ expect(trace.coderFinishedAt).toBeGreaterThanOrEqual(trace.runCodeAt[0]!);
});
+});
- it('routes effort:high specs to the high model and low/string specs to the default', async () => {
- const modelsByBrief: Record<string, string> = {};
- const { dispatchTool, tracker, editTraces } = setup({
- runSnippet: async (brief, _context, model) => {
- modelsByBrief[brief] = (model as { modelId: string }).modelId;
- return { text: `composed: ${brief}`, totalUsage: usage };
- },
- });
- await dispatchTool.execute?.(
- {
- edits: [
- {
- editing_instruction: 'insert snippets.plain and snippets.fancy',
- snippet_specs: {
- plain: 'a one-line caption',
- fancy: { brief: 'a long poem', effort: 'high' },
- },
- },
- ],
- },
- callOptions
+describe('dispatch -- onInputAvailable early launch', () => {
+ it('runs the edit once; execute joins it and marks the trace', async () => {
+ const { tool, editTraces, tasks } = setup();
+ const edit = { editing_instruction: 'convert the paragraph to a heading' };
+ tool.onInputAvailable?.({ input: edit, toolCallId: 't1', messages: [] });
+ const out = await tool.execute?.(edit, { toolCallId: 't1', messages: [] });
+ expect(out).toContain('✓ APPLIED');
+ expect(tasks).toEqual(['convert the paragraph to a heading']);
+ const trace = editTraces[0]!;
+ expect(trace.streamedAt).toBeGreaterThan(0);
+ expect(trace.coderFinishedAt).toBeGreaterThanOrEqual(trace.streamedAt!);
+ });
+
+ it('execute starts the coder if onInputAvailable did not fire', async () => {
+ const { tool, editTraces, tasks } = setup();
+ await tool.execute?.(
+ { editing_instruction: 'late edit' },
+ { toolCallId: 't1', messages: [] }
);
- expect(modelsByBrief).toEqual({
- 'a one-line caption': 'snip-model',
- 'a long poem': 'snip-high-model',
- });
- expect(tracker.toEntries()).toContainEqual({
- model: 'snip-high-model',
- inputTokens: 10,
- outputTokens: 5,
- });
- expect(editTraces[0]![0]!.snippets).toMatchObject([
- { key: 'plain', effort: 'low' },
- { key: 'fancy', effort: 'high' },
- ]);
+ expect(tasks).toEqual(['late edit']);
+ expect(editTraces[0]!.streamedAt).toBeUndefined();
});
- it('survives a rejecting spec the writer never awaits and traces the error', async () => {
- const { dispatchTool, editTraces } = setup({
- runSnippet: async () => {
- throw new Error('model unavailable');
- },
+ it('keeps calls from different tool call ids separate', async () => {
+ const { tool, tasks } = setup();
+ tool.onInputAvailable?.({
+ input: { editing_instruction: 'other edit' },
+ toolCallId: 'other-call',
+ messages: [],
});
- const out = await dispatchTool.execute?.(
- {
- edits: [
- {
- editing_instruction: 'do something else entirely',
- snippet_specs: { unused: 'never referenced' },
- },
- ],
- },
- callOptions
+ await tool.execute?.(
+ { editing_instruction: 'this edit' },
+ { toolCallId: 't1', messages: [] }
);
- expect(out).toContain('APPLIED');
- // the trace tap runs on a microtask after the batch resolves
- await new Promise((resolve) => setTimeout(resolve, 0));
- expect(editTraces[0]![0]!.snippets[0]).toMatchObject({
- key: 'unused',
- error: 'model unavailable',
- });
+ expect(tasks.sort()).toEqual(['other edit', 'this edit']);
});
});
diff --git a/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts b/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts
index 3674b00740..def62b8da1 100644
--- a/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts
+++ b/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts
@@ -1,20 +1,13 @@
import { type LanguageModel, tool } from 'ai';
import { z } from 'zod';
import type { coder } from '../agents';
-import type { snippet } from '../agents/snippet';
import type { LexicalSession } from '../ai-toolkit';
import type { AwarenessSource } from '../awareness';
import type { Doc } from '../doc';
import type { DocumentOpQueueParams } from '../queue';
-import type { SnippetSource } from '../runtime';
import type { TokenTracker } from '../token-tracker';
import { numberLines, serializeWithXml } from '../utils';
import type { RunCodeToolOptions } from './run-code';
-import {
- launchSnippetSpecs,
- SnippetSpecsSchema,
- type SnippetTraceEntry,
-} from './snippets';
export type { UsageEntry } from '../token-tracker';
export { TokenTracker } from '../token-tracker';
@@ -67,7 +60,7 @@ function findBlocked(
return null;
}
-export function mergeRanges(
+function mergeRanges(
ranges: Array<[number, number]>
): Array<[number, number]> {
const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
@@ -80,7 +73,7 @@ export function mergeRanges(
return merged;
}
-export function indexXmlRanges(xml: string): {
+function indexXmlRanges(xml: string): {
lines: string[];
byId: Map<string, XmlNodeRange>;
} {
@@ -198,25 +191,27 @@ export type Writer = {
release: () => void;
};
-/** Per-edit timing recorded by dispatch: the snippet windows, the writer's
- * window, and when each of its `runCode` calls executed. Comparing a
- * snippet's `resolvedAt` with the first `runCodeAt` shows whether the settle
- * point actually waited or generation was fully masked by codegen. */
+/** Per-edit timing recorded by dispatch: the writer's window and when each of
+ * its `runCode` calls executed. */
export type DispatchEditTrace = {
- snippets: SnippetTraceEntry[];
+ /** Set when this edit was launched from onInputAvailable, before execute ran.
+ * Epoch ms. */
+ streamedAt?: number;
coderStartedAt: number;
coderFinishedAt: number;
runCodeAt: number[];
};
+/** 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 DispatchToolOptions = {
session: LexicalSession;
childModel: LanguageModel;
- snippetModel: LanguageModel;
- /** Stronger composition model used for `effort: "high"` snippet specs. */
- snippetHighModel: LanguageModel;
tracker: TokenTracker;
- runSnippet: typeof snippet;
+ /** The user's original edit request, shown to every writer for tone/intent. */
+ request?: string;
runner: RunCodeToolOptions['runner'];
params?: DocumentOpQueueParams;
typingAnimations?: boolean;
@@ -226,20 +221,28 @@ export type DispatchToolOptions = {
runTask: typeof coder;
serialize?: (session: LexicalSession) => string;
onOps?: RunCodeToolOptions['onOps'];
- /** Called after each dispatch batch with the JS code blocks run by each coder. */
- onCoderResult?: (codes: string[][]) => void;
- /** Called after each dispatch batch with per-edit snippet + timing traces. */
- onEditTrace?: (edits: DispatchEditTrace[]) => void;
+ /** Called after each dispatch call with the coder's runCode calls. */
+ onCoderResult?: (codes: CoderRunCode[]) => void;
+ /** Called after each dispatch call with the edit's timing trace. */
+ onEditTrace?: (edit: DispatchEditTrace) => void;
};
+export const DispatchEditSchema = z.object({
+ editing_instruction: z
+ .string()
+ .describe(
+ 'the changes you want applied to the document. writers see the user request and compose content themselves — describe the structural change and any shape/length constraints; include exact strings (quotes, ids, user-supplied text) verbatim when the writer must use them character-for-character'
+ ),
+});
+
+export type DispatchEdit = z.infer<typeof DispatchEditSchema>;
+
export function createDispatchTool(opts: DispatchToolOptions) {
const {
session,
childModel,
- snippetModel,
- snippetHighModel,
tracker,
- runSnippet,
+ request,
params,
typingAnimations,
sleep,
@@ -252,100 +255,99 @@ export function createDispatchTool(opts: DispatchToolOptions) {
onEditTrace,
} = opts;
const serialize = opts.serialize ?? serializeWithXml;
- return tool({
- description:
- 'spawn a writer to carry out an edit instruction on the document',
- inputSchema: z.object({
- edits: z
- .array(
- z.object({
- editing_instruction: z
- .string()
- .describe('mechanical changes you want applied to the document'),
- snippets: z
- .record(z.string(), z.string())
- .optional()
- .describe(
- 'verbatim text values injected as a `snippets` JS object the coder can use directly. all verbatim text goes here, so that the writer can paste it in'
- ),
- snippet_specs: SnippetSpecsSchema.optional().describe(
- 'content to be composed by a snippet writer while your writer works: key → brief (what to write, tone, expected shape/length), or `{ brief, effort: "high" }` to route to the stronger composition model. the writer references it as `snippets.KEY` like any verbatim snippet'
- ),
- })
- )
- .describe('edit instructions to run as one parallel batch'),
- }),
- execute: async ({ edits }) => {
- const xml = serializeWithXml(session);
- const contexts = edits.map((e) =>
- computeContextRange(xml, e.editing_instruction)
- );
- const editTraces: DispatchEditTrace[] = [];
- // Writers run concurrently (distinct cursors); each applies its own ops
- // serially via editor.update, so the shared session never tears.
- const results = await Promise.all(
- edits.map(
- async ({ editing_instruction, snippets, snippet_specs }, i) => {
- const context = xmlWindow(xml, contexts[i]!);
- const { pending, traces: snippetTraces } = launchSnippetSpecs({
- specs: snippet_specs,
- context,
- snippetModel,
- snippetHighModel,
- tracker,
- runSnippet,
- signal,
- });
- const merged: SnippetSource = { ...snippets, ...pending };
- const trace: DispatchEditTrace = {
- snippets: snippetTraces,
- coderStartedAt: Date.now(),
- coderFinishedAt: 0,
- runCodeAt: [],
- };
- editTraces[i] = trace;
- const writer = await makeWriter();
- const { doc, awarenessSource } = writer;
- try {
- return await runTask(session, editing_instruction, childModel, {
- doc,
- awarenessSource,
- context,
- snippets: merged,
- params,
- typingAnimations,
- sleep,
- signal,
- runner,
- onOps,
- onRunCode: () => trace.runCodeAt.push(Date.now()),
- });
- } finally {
- trace.coderFinishedAt = Date.now();
- writer.release();
- }
- }
- )
- );
- onEditTrace?.(editTraces);
- const summaries = results.map((res, i) => {
- tracker.add(childModel as { modelId: string }, res.totalUsage);
- const blocked = findBlocked(res);
- if (blocked) {
- return `${i + 1}. ⚠ BLOCKED -- ${blocked.message}.`;
- }
- return `${i + 1}. ✓ APPLIED`;
+
+ type CoderRun = Awaited<ReturnType<typeof runTask>>;
+ type EditRun = { run: Promise<CoderRun>; trace: DispatchEditTrace };
+ // Coders already started from onInputAvailable, keyed by tool call id.
+ const calls = new Map<string, EditRun>();
+
+ async function runEdit(
+ edit: DispatchEdit,
+ trace: DispatchEditTrace
+ ): Promise<CoderRun> {
+ // Serialized at launch time so an edit launched early sees whatever earlier
+ // coders have already applied.
+ const xml = serializeWithXml(session);
+ const context = xmlWindow(
+ xml,
+ computeContextRange(xml, edit.editing_instruction)
+ );
+ const writer = await makeWriter();
+ const { doc, awarenessSource } = writer;
+ try {
+ return await runTask(session, edit.editing_instruction, childModel, {
+ doc,
+ awarenessSource,
+ context,
+ request,
+ params,
+ typingAnimations,
+ sleep,
+ signal,
+ runner,
+ onOps,
+ onRunCode: () => trace.runCodeAt.push(Date.now()),
});
- if (onCoderResult) {
- const codes = results.map((res) =>
- res.steps
+ } finally {
+ trace.coderFinishedAt = Date.now();
+ writer.release();
+ }
+ }
+
+ /** Start the edit if it isn't already running; return its run either way. */
+ function ensureLaunched(
+ toolCallId: string,
+ edit: DispatchEdit,
+ streamed: boolean
+ ): EditRun {
+ const existing = calls.get(toolCallId);
+ if (existing) return existing;
+ const trace: DispatchEditTrace = {
+ streamedAt: streamed ? Date.now() : undefined,
+ coderStartedAt: Date.now(),
+ coderFinishedAt: 0,
+ runCodeAt: [],
+ };
+ const entry: EditRun = { run: runEdit(edit, trace), trace };
+ // 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(() => {});
+ calls.set(toolCallId, entry);
+ return entry;
+ }
+
+ return {
+ tool: tool({
+ description:
+ 'spawn a writer for one edit instruction; call in parallel for independent edits',
+ inputSchema: DispatchEditSchema,
+ onInputAvailable: ({ input, toolCallId }) => {
+ ensureLaunched(toolCallId, input, true);
+ },
+ execute: async (edit, { toolCallId }) => {
+ const entry = ensureLaunched(toolCallId, edit, false);
+ calls.delete(toolCallId);
+ const result = await entry.run;
+ onEditTrace?.(entry.trace);
+ tracker.add(childModel as { modelId: string }, result.totalUsage);
+ const blocked = findBlocked(result);
+ const summary = blocked
+ ? `⚠ BLOCKED -- ${blocked.message}.`
+ : `✓ APPLIED`;
+ if (onCoderResult) {
+ const codes = result.steps
.flatMap((step) => step.toolCalls)
.filter((call) => call.toolName === 'runCode')
- .map((call) => (call.input as { code: string }).code)
- );
- onCoderResult(codes);
- }
- return `${summaries.join('\n')}\n\n<document>\n${serialize(session)}\n</document>`;
- },
- });
+ .map((call) => {
+ const { code, snippets } = call.input as CoderRunCode;
+ return { code, snippets };
+ });
+ onCoderResult(codes);
+ }
+ return `${summary}\n\n<document>\n${serialize(session)}\n</document>`;
+ },
+ }),
+ };
}
+
+export type DispatchTool = ReturnType<typeof createDispatchTool>;
diff --git a/js/ai-editing-worker/src/ai-editing/tools/index.ts b/js/ai-editing-worker/src/ai-editing/tools/index.ts
index 53d47c0de0..507522befb 100644
--- a/js/ai-editing-worker/src/ai-editing/tools/index.ts
+++ b/js/ai-editing-worker/src/ai-editing/tools/index.ts
@@ -2,4 +2,3 @@ export * from './dispatch';
export * from './im-blocked';
export * from './read-document';
export * from './run-code';
-export * from './snippets';
diff --git a/js/ai-editing-worker/src/ai-editing/tools/run-code.ts b/js/ai-editing-worker/src/ai-editing/tools/run-code.ts
index 0e9ac1a592..c0ba7b6fcd 100644
--- a/js/ai-editing-worker/src/ai-editing/tools/run-code.ts
+++ b/js/ai-editing-worker/src/ai-editing/tools/run-code.ts
@@ -5,38 +5,45 @@ import type { AwarenessSource } from '../awareness';
import type { Doc } from '../doc';
import type { DocumentOp } from '../editor';
import type { DocumentOpQueueParams } from '../queue';
-import { type CodeRunner, runEditorCode, type SnippetSource } from '../runtime';
+import { type CodeRunner, runEditorCode } from '../runtime';
export type RunCodeToolOptions = {
session: LexicalSession;
doc: Doc;
awarenessSource: AwarenessSource;
runner: CodeRunner;
- snippets?: SnippetSource;
params?: DocumentOpQueueParams;
typingAnimations?: boolean;
sleep?: (ms: number) => Promise<void>;
onOps?: (ops: DocumentOp[]) => void;
- /** Called when a runCode call begins executing (before snippets settle). */
- onRunCode?: () => void;
+ /** Called when a runCode call begins executing. */
+ onRunCode?: (snippets?: Record<string, string>) => void;
};
/** The writer's one tool: run a JS snippet against `editor`, returning compact
* success or error output. The snippet's only scope is
- * `editor`; the system animates + applies the resulting ops live. */
+ * `editor` and `snippets`; the system animates + applies the resulting ops live. */
export function createRunCodeTool(opts: RunCodeToolOptions) {
return tool({
description:
- "Run JS statements against `editor` (the ONLY in-scope value) to edit the document — e.g. `editor.convertToHeading('b3', 2); editor.bold('b5', 'word')`. Returns `ok`, or an error naming a bad id so you can retry.",
- inputSchema: z.object({ code: z.string() }),
- execute: async ({ code }) => {
- opts.onRunCode?.();
+ "Run JS statements against `editor` (the ONLY in-scope value besides `snippets`) to edit the document — e.g. `editor.convertToHeading('b3', 2); editor.bold('b5', 'word')`. Returns `ok`, or an error naming a bad id so you can retry.",
+ inputSchema: z.object({
+ code: z.string(),
+ snippets: z
+ .record(z.string(), z.string())
+ .optional()
+ .describe(
+ '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).'
+ ),
+ }),
+ execute: async ({ code, snippets }) => {
+ opts.onRunCode?.(snippets);
const result = await runEditorCode({
session: opts.session,
doc: opts.doc,
code,
awarenessSource: opts.awarenessSource,
- snippets: opts.snippets,
+ snippets,
params: opts.params,
typingAnimations: opts.typingAnimations,
sleep: opts.sleep,
diff --git a/js/ai-editing-worker/src/ai-editing/tools/snippets.ts b/js/ai-editing-worker/src/ai-editing/tools/snippets.ts
deleted file mode 100644
index 5827cb3406..0000000000
--- a/js/ai-editing-worker/src/ai-editing/tools/snippets.ts
+++ /dev/null
@@ -1,89 +0,0 @@
-import type { LanguageModel } from 'ai';
-import { z } from 'zod';
-import type { snippet } from '../agents/snippet';
-import type { PendingSnippet, PendingSnippetEffort } from '../runtime';
-import type { TokenTracker } from '../token-tracker';
-
-/** A snippet spec as the supervisor writes it: a plain brief (low effort), or
- * `{ brief, effort }` to route composition to the stronger model. */
-export const SnippetSpecsSchema = z.record(
- z.string(),
- z.union([
- z.string(),
- z.object({
- brief: z.string(),
- effort: z.enum(['low', 'high']).optional(),
- }),
- ])
-);
-
-export type SnippetSpecs = z.infer<typeof SnippetSpecsSchema>;
-
-/** One spec'd snippet's life, timestamped (epoch ms) for the session trace.
- * `resolvedAt` stays unset if generation was still in flight when the batch
- * finished (a spec no writer awaited). */
-export type SnippetTraceEntry = {
- key: string;
- brief: string;
- effort?: PendingSnippetEffort;
- text?: string;
- error?: string;
- startedAt: number;
- resolvedAt?: number;
-};
-
-export type LaunchSnippetSpecsOptions = {
- specs: SnippetSpecs | undefined;
- /** Document window the snippet text will land in. */
- context: string;
- snippetModel: LanguageModel;
- snippetHighModel: LanguageModel;
- tracker: TokenTracker;
- runSnippet: typeof snippet;
- signal?: AbortSignal;
-};
-
-/** Fire one snippet agent per spec — immediately, without awaiting — so
- * composition overlaps the writer's codegen. The returned promises settle
- * only when the writer's code runs (see `settleSnippets`). */
-export function launchSnippetSpecs(opts: LaunchSnippetSpecsOptions): {
- pending: Record<string, PendingSnippet>;
- traces: SnippetTraceEntry[];
-} {
- const traces: SnippetTraceEntry[] = [];
- const pending: Record<string, PendingSnippet> = Object.fromEntries(
- Object.entries(opts.specs ?? {}).map(([key, spec]) => {
- const { brief, effort = 'low' as PendingSnippetEffort } =
- typeof spec === 'string' ? { brief: spec } : spec;
- const model =
- effort === 'high' ? opts.snippetHighModel : opts.snippetModel;
- const entry: SnippetTraceEntry = {
- key,
- brief,
- effort,
- startedAt: Date.now(),
- };
- traces.push(entry);
- const promise = opts
- .runSnippet(brief, opts.context, model, opts.signal)
- .then((res) => {
- opts.tracker.add(model as { modelId: string }, res.totalUsage);
- return res.text;
- });
- // Trace tap; doubles as the unhandled-rejection guard for specs
- // the writer never awaits.
- promise.then(
- (text) => {
- entry.text = text;
- entry.resolvedAt = Date.now();
- },
- (e: unknown) => {
- entry.error = e instanceof Error ? e.message : String(e);
- entry.resolvedAt = Date.now();
- }
- );
- return [key, { brief, promise }];
- })
- );
- return { pending, traces };
-}
diff --git a/js/ai-editing-worker/src/endpoints/edit.ts b/js/ai-editing-worker/src/endpoints/edit.ts
index 07da50c64c..0edec6fb9a 100644
--- a/js/ai-editing-worker/src/endpoints/edit.ts
+++ b/js/ai-editing-worker/src/endpoints/edit.ts
@@ -45,11 +45,6 @@ const EditBody = z.object({
supervisor: ModelListSchema,
interpret: ModelListSchema,
coding: ModelListSchema,
- /** Snippet-composition model; falls back to the coding list when omitted. */
- snippet: ModelListSchema.optional(),
- /** Model for `effort: "high"` snippet specs; falls back to the supervisor
- * list when omitted, so high effort escalates to the strongest model. */
- snippetHigh: ModelListSchema.optional(),
}),
typingAnimations: z.boolean().optional(),
/** Animation speed multiplier applied while nobody is watching the doc. */
@@ -123,8 +118,6 @@ edit.post('/', zValidator('json', EditBody), async (c) => {
supervisor: resolveModel(models.supervisor),
interpret: resolveModel(models.interpret),
coding: resolveModel(models.coding),
- snippet: resolveModel(models.snippet ?? models.coding),
- snippetHigh: resolveModel(models.snippetHigh ?? models.supervisor),
},
typingAnimations,
sleep,
diff --git a/js/ai-editing-worker/src/run-edit.ts b/js/ai-editing-worker/src/run-edit.ts
index f30a58d79a..eaa2eceb13 100644
--- a/js/ai-editing-worker/src/run-edit.ts
+++ b/js/ai-editing-worker/src/run-edit.ts
@@ -8,7 +8,7 @@ import {
import { MARKDOWN_LORO_SCHEMA } from '../../lexical-core/markdown-loro-schema';
import { supervisor } from './ai-editing/agents';
import type { DocumentOp } from './ai-editing/editor';
-import type { DispatchEditTrace } from './ai-editing/tools';
+import type { CoderRunCode, DispatchEditTrace } from './ai-editing/tools';
import type { CodeRunner } from './ai-editing/runtime';
import type { UsageEntry } from './ai-editing/token-tracker';
import { serializeWithXml } from './ai-editing/utils';
@@ -31,9 +31,6 @@ export type ResolvedModels = {
supervisor: LanguageModel;
interpret: LanguageModel;
coding: LanguageModel;
- snippet: LanguageModel;
- /** Stronger composition model for `effort: "high"` snippet specs. */
- snippetHigh: LanguageModel;
};
export type RunEditArgs = {
@@ -102,9 +99,7 @@ export async function runEditSession(
const workspace = new EditingWorkspace(manager, source, wal);
const allOps: DocumentOp[] = [];
- // code, per coder, per batch
- const coderCodeBlocks: string[][][] = [];
- // snippet + timing traces, per edit, per batch
+ const coderCodeBlocks: CoderRunCode[][][] = [];
const dispatchEditTraces: DispatchEditTrace[][] = [];
const sessionId = crypto.randomUUID();
const startedAt = new Date();
@@ -125,8 +120,8 @@ export async function runEditSession(
interpret: args.interpret,
runner: args.runner,
onOps: (ops) => allOps.push(...ops),
- onCoderResult: (codes) => coderCodeBlocks.push(codes),
- onEditTrace: (edits) => dispatchEditTraces.push(edits),
+ onCoderResult: (codes) => coderCodeBlocks.push([codes]),
+ onEditTrace: (edit) => dispatchEditTraces.push([edit]),
});
// Drain the queued propagates (plus a final catch-all sync) and ensure every
diff --git a/js/ai-editing-worker/src/trace-log.ts b/js/ai-editing-worker/src/trace-log.ts
index 576d03f410..9dfb9b3df9 100644
--- a/js/ai-editing-worker/src/trace-log.ts
+++ b/js/ai-editing-worker/src/trace-log.ts
@@ -1,6 +1,6 @@
import type { StepResult, ToolSet } from 'ai';
import type { UsageEntry } from './ai-editing/token-tracker';
-import type { DispatchEditTrace } from './ai-editing/tools';
+import type { CoderRunCode, DispatchEditTrace } from './ai-editing/tools';
/** Raw inputs collected during a run, normalized into a TraceSession. */
export type TraceMeta = {
@@ -12,8 +12,8 @@ export type TraceMeta = {
intent?: string;
/** Wall-clock duration of the interpreter pass, in ms. */
interpretDurationMs?: number;
- /** JS code blocks run by each coder, indexed by dispatch round then edit index. */
- coderCodeBlocks?: string[][][];
+ /** Each coder's runCode calls, indexed by dispatch round then edit index. */
+ coderCodeBlocks?: CoderRunCode[][][];
/** Snippet + timing traces, indexed by dispatch round then edit index. */
dispatchEditTraces?: DispatchEditTrace[][];
/** Wall-clock duration of each supervisor step, in ms. */
@@ -49,7 +49,7 @@ export type TraceSession = {
interpretDurationMs?: number;
steps: TraceStep[];
usage: Usage;
- coderCodeBlocks?: string[][][];
+ coderCodeBlocks?: CoderRunCode[][][];
dispatchEditTraces?: DispatchEditTrace[][];
};
@@ -89,8 +89,6 @@ export function buildTraceSession(
type TraceDispatchEdit = {
editing_instruction: string;
context?: { start_line: number; end_line: number };
- snippets?: Record<string, string>;
- snippet_specs?: Record<string, string | { brief: string; effort?: string }>;
};
/** Render an epoch-ms timestamp relative to the session start, e.g. `t+2.1s`. */
@@ -99,165 +97,166 @@ function relTime(ms: number | undefined, t0: number | undefined): string {
return `t+${((ms - t0) / 1000).toFixed(1)}s`;
}
-function formatDispatchArgs(
- args: { edits: TraceDispatchEdit[] },
- codesPerEdit?: string[][],
- editTraces?: DispatchEditTrace[],
- t0?: number
+function indented(text: string): string {
+ return text
+ .split('\n')
+ .map((l) => ` ${l}`)
+ .join('\n');
+}
+
+/** Step header timing, e.g. `· 0.9s · t+1.4s` (this step / cumulative). */
+function formatTiming(durationMs?: number, elapsedMs?: number): string {
+ const parts: string[] = [];
+ if (durationMs != null) parts.push(`${(durationMs / 1000).toFixed(1)}s`);
+ if (elapsedMs != null) parts.push(`t+${(elapsedMs / 1000).toFixed(1)}s`);
+ return parts.length > 0 ? ` · ${parts.join(' · ')}` : '';
+}
+
+function formatEditEntry(
+ edit: TraceDispatchEdit,
+ index: number,
+ codes: CoderRunCode[] | undefined,
+ trace: DispatchEditTrace | undefined,
+ t0: number | undefined
): string {
- return args.edits
- .map((e, i) => {
- const range = e.context
- ? ` [lines ${e.context.start_line}-${e.context.end_line}]`
- : '';
- let out = `${i + 1}. ${e.editing_instruction}${range}`;
- if (e.snippets && Object.keys(e.snippets).length > 0) {
- for (const [key, value] of Object.entries(e.snippets)) {
- const text =
- typeof value === 'string' ? value : JSON.stringify(value, null, 2);
- out += `\n snippets.${key}:\n \`\`\`\n${text
- .split('\n')
- .map((l) => ` ${l}`)
- .join('\n')}\n \`\`\``;
- }
- }
- if (e.snippet_specs && Object.keys(e.snippet_specs).length > 0) {
- for (const [key, spec] of Object.entries(e.snippet_specs)) {
- const brief = typeof spec === 'string' ? spec : spec.brief;
- const effort = typeof spec === 'string' ? undefined : spec.effort;
- out += `\n snippet_specs.${key}${effort === 'high' ? ' [high]' : ''}: ${brief}`;
- }
- }
- const trace = editTraces?.[i];
- if (trace) {
- for (const s of trace.snippets) {
- const window = `${relTime(s.startedAt, t0)} → ${
- s.resolvedAt == null ? 'unresolved' : relTime(s.resolvedAt, t0)
- }`;
- out += `\n snippet ${s.key}${s.effort === 'high' ? ' · high' : ''} · ${window}${s.error ? ` · ⚠ ${s.error}` : ''}`;
- if (s.text) {
- out += `\n \`\`\`\n${s.text
- .split('\n')
- .map((l) => ` ${l}`)
- .join('\n')}\n \`\`\``;
- }
- }
- const runCodes = trace.runCodeAt
- .map((ms) => relTime(ms, t0))
- .join(', ');
- out += `\n coder ${relTime(trace.coderStartedAt, t0)} → ${relTime(trace.coderFinishedAt, t0)}${runCodes ? ` · runCode at ${runCodes}` : ''}`;
- }
- const codes = codesPerEdit?.[i];
- if (codes && codes.length > 0) {
- for (const code of codes) {
- out += `\n\n \`\`\`js\n${code
- .split('\n')
- .map((l) => ` ${l}`)
- .join('\n')}\n \`\`\``;
- }
+ const range = edit.context
+ ? ` [lines ${edit.context.start_line}-${edit.context.end_line}]`
+ : '';
+ const parts: string[] = [`${index + 1}. ${edit.editing_instruction}${range}`];
+
+ if (trace) {
+ const runCodes = trace.runCodeAt.map((ms) => relTime(ms, t0)).join(', ');
+ // `streamed` = the coder launched from the streaming dispatch args,
+ // before the supervisor finished writing the batch.
+ const streamed = trace.streamedAt != null ? ' · streamed' : '';
+ parts.push(
+ ` coder ${relTime(trace.coderStartedAt, t0)} → ${relTime(trace.coderFinishedAt, t0)}${streamed}${runCodes ? ` · runCode at ${runCodes}` : ''}`
+ );
+ }
+
+ if (codes && codes.length > 0) {
+ for (const call of codes) {
+ 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 \`\`\``
+ );
}
- return out;
- })
- .join('\n');
+ }
+ }
+
+ return parts.join('\n');
+}
+
+function formatDispatchInput(
+ edit: TraceDispatchEdit,
+ codes: CoderRunCode[] | undefined,
+ trace: DispatchEditTrace | undefined,
+ t0: number | undefined
+): string {
+ // A malformed supervisor tool call can land `editing_instruction` as something
+ // other than a string (the model emitting `<parameter …>` markup instead of a
+ // JSON string). Render it verbatim rather than crashing the whole trace.
+ if (typeof edit?.editing_instruction !== 'string') {
+ return indented(
+ `⚠ malformed dispatch args (editing_instruction is ${typeof edit?.editing_instruction}, not a string):\n${JSON.stringify(edit)}`
+ );
+ }
+ return formatEditEntry(edit, 0, codes, trace, t0);
+}
+
+function formatDispatchOutput(output: unknown): string[] {
+ const res = String(output);
+ const docStart = res.indexOf('<document>');
+ const docEnd = res.indexOf('</document>');
+ const lines: string[] = [];
+
+ const summary = docStart !== -1 ? res.slice(0, docStart).trim() : res.trim();
+ if (summary) lines.push('', '**result:**', summary);
+
+ if (docStart !== -1 && docEnd !== -1) {
+ lines.push(
+ '',
+ '**document after:**',
+ '```xml',
+ res.slice(docStart + '<document>'.length, docEnd).trim(),
+ '```'
+ );
+ }
+
+ return lines;
}
function formatToolCall(
call: TraceToolCall,
- codesPerEdit?: string[][],
+ codesPerEdit?: CoderRunCode[][],
editTraces?: DispatchEditTrace[],
t0?: number
): string {
- const lines: string[] = [];
const { output } = call;
+ const lines: string[] = [];
if (call.toolName === 'dispatch') {
- const { edits } = call.input as { edits: TraceDispatchEdit[] };
- lines.push(`**dispatch** — ${edits.length} edit(s)`);
- lines.push('');
- lines.push(formatDispatchArgs({ edits }, codesPerEdit, editTraces, t0));
- if (output != null) {
- const res = String(output);
- const docStart = res.indexOf('<document>');
- const docEnd = res.indexOf('</document>');
- const summary =
- docStart !== -1 ? res.slice(0, docStart).trim() : res.trim();
- if (summary) {
- lines.push('');
- lines.push('**result:**');
- lines.push(summary);
- }
- if (docStart !== -1 && docEnd !== -1) {
- lines.push('');
- lines.push('**document after:**');
- lines.push('```xml');
- lines.push(res.slice(docStart + '<document>'.length, docEnd).trim());
- lines.push('```');
- }
- }
+ const edit = call.input as TraceDispatchEdit;
+ const valid = typeof edit?.editing_instruction === 'string';
+ lines.push(`**dispatch** — ${valid ? '1 edit' : '⚠ malformed'}`);
+ lines.push(
+ '',
+ formatDispatchInput(edit, codesPerEdit?.[0], editTraces?.[0], t0)
+ );
+ if (output != null) lines.push(...formatDispatchOutput(output));
} else if (call.toolName === 'readDocument') {
- lines.push(`**readDocument**`);
- if (output != null) {
- lines.push('');
- lines.push('```xml');
- lines.push(String(output).trim());
- lines.push('```');
- }
+ lines.push('**readDocument**');
+ if (output != null) lines.push('', '```xml', String(output).trim(), '```');
} else {
- lines.push(`**${call.toolName}**`);
- lines.push('```json');
- lines.push(JSON.stringify(call.input, null, 2));
- lines.push('```');
- if (output != null) {
- lines.push('');
- lines.push('**result:**');
- lines.push(String(output).slice(0, 400));
- }
+ lines.push(
+ `**${call.toolName}**`,
+ '```json',
+ JSON.stringify(call.input, null, 2),
+ '```'
+ );
+ if (output != null)
+ lines.push('', '**result:**', String(output).slice(0, 400));
}
return lines.join('\n');
}
-/** Step header timing, e.g. `· 0.9s · t+1.4s` (this step / cumulative). */
-function formatTiming(durationMs?: number, elapsedMs?: number): string {
- const parts: string[] = [];
- if (durationMs != null) parts.push(`${(durationMs / 1000).toFixed(1)}s`);
- if (elapsedMs != null) parts.push(`t+${(elapsedMs / 1000).toFixed(1)}s`);
- return parts.length > 0 ? ` · ${parts.join(' · ')}` : '';
-}
-
function formatStep(
step: TraceStep,
- i: number,
+ index: number,
elapsedMs: number | undefined,
- dispatchRoundRef: { current: number },
- coderCodeBlocks?: string[][][],
- dispatchEditTraces?: DispatchEditTrace[][],
- t0?: number
-): string {
+ dispatchRound: number,
+ coderCodeBlocks: CoderRunCode[][][] | undefined,
+ dispatchEditTraces: DispatchEditTrace[][] | undefined,
+ t0: number | undefined
+): { rendered: string; nextDispatchRound: number } {
const lines: string[] = [
- `### Step ${i + 1}${formatTiming(step.durationMs, elapsedMs)}`,
+ `### Step ${index + 1}${formatTiming(step.durationMs, elapsedMs)}`,
];
- if (step.text) {
- lines.push('');
- lines.push(step.text.trim());
- }
+ if (step.text) lines.push('', step.text.trim());
+ let round = dispatchRound;
for (const call of step.toolCalls) {
- const round =
- call.toolName === 'dispatch' ? dispatchRoundRef.current++ : undefined;
- const codesPerEdit = round == null ? undefined : coderCodeBlocks?.[round];
- const editTraces = round == null ? undefined : dispatchEditTraces?.[round];
- lines.push('');
- lines.push(formatToolCall(call, codesPerEdit, editTraces, t0));
+ const callRound = call.toolName === 'dispatch' ? round++ : undefined;
+ lines.push(
+ '',
+ formatToolCall(
+ call,
+ callRound == null ? undefined : coderCodeBlocks?.[callRound],
+ callRound == null ? undefined : dispatchEditTraces?.[callRound],
+ t0
+ )
+ );
}
- lines.push('');
lines.push(
+ '',
`*${step.inputTokens.toLocaleString()} in / ${step.outputTokens.toLocaleString()} out*`
);
- return lines.join('\n');
+ return { rendered: lines.join('\n'), nextDispatchRound: round };
}
/** Render the stored session into the human-readable markdown trace. */
@@ -292,28 +291,28 @@ export function renderTraceMarkdown(session: TraceSession): string {
sections.push('', '---', '', '## Supervisor');
- const dispatchRoundRef = { current: 0 };
const t0 = Date.parse(session.startedAt);
+ const t0OrUndefined = Number.isNaN(t0) ? undefined : t0;
let elapsedMs = 0;
let sawDuration = false;
+ let dispatchRound = 0;
for (let i = 0; i < session.steps.length; i++) {
const step = session.steps[i]!;
if (step.durationMs != null) {
elapsedMs += step.durationMs;
sawDuration = true;
}
- sections.push('');
- sections.push(
- formatStep(
- step,
- i,
- sawDuration ? elapsedMs : undefined,
- dispatchRoundRef,
- session.coderCodeBlocks,
- session.dispatchEditTraces,
- Number.isNaN(t0) ? undefined : t0
- )
+ const { rendered, nextDispatchRound } = formatStep(
+ step,
+ i,
+ sawDuration ? elapsedMs : undefined,
+ dispatchRound,
+ session.coderCodeBlocks,
+ session.dispatchEditTraces,
+ t0OrUndefined
);
+ sections.push('', rendered);
+ dispatchRound = nextDispatchRound;
}
sections.push(
diff --git a/js/ai-editing-worker/vitest.config.ts b/js/ai-editing-worker/vitest.config.ts
new file mode 100644
index 0000000000..87da773488
--- /dev/null
+++ b/js/ai-editing-worker/vitest.config.ts
@@ -0,0 +1,18 @@
+import { defineConfig, type Plugin } from 'vitest/config';
+
+/** Wrangler bundles `**\/*.md` as text modules (see wrangler.toml [[rules]]);
+ * mirror that for tests so files importing prompts are loadable. */
+function mdAsText(): Plugin {
+ return {
+ name: 'md-as-text',
+ enforce: 'pre',
+ transform(code, id) {
+ if (!id.endsWith('.md')) return null;
+ return { code: `export default ${JSON.stringify(code)};`, map: null };
+ },
+ };
+}
+
+export default defineConfig({
+ plugins: [mdAsText()],
+});