Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
fix: add database for traces (#4550)
Wolf Mermelstein3d89bb18934f
diff --git a/.github/workflows/deploy_ai_editing_worker.yml b/.github/workflows/deploy_ai_editing_worker.ymlnew file mode 100644index 0000000000..aa17135ff8--- /dev/null+++ b/.github/workflows/deploy_ai_editing_worker.yml@@ -0,0 +1,45 @@+# DO NOT EDIT — regenerate with `cargo x workflows` (from rust/cloud-storage).+# Source: rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/deploy_ai_editing_worker.rs+name: Deploy AI Editing Worker+'on':+ push:+ branches:+ - main+ paths:+ - '.github/workflows/deploy_ai_editing_worker.yml'+ - js/bun.lock+ - js/package.json+ - js/ai-editing-worker/**+ - js/app/packages/core/**+ - js/app/packages/websocket/**+ - js/loro-mirror/**+ workflow_dispatch:+ inputs:+ environment:+ description: Environment to deploy (dev or prod)+ type: string+ default: dev+jobs:+ deploy:+ name: Deploy to Cloudflare+ runs-on: namespace-profile-linux-small+ steps:+ - name: Checkout+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd+ with:+ clean: 'false'+ persist-credentials: 'false'+ - name: Setup Bun+ uses: oven-sh/setup-bun@v2+ - name: Install dependencies+ run: bun install --frozen-lockfile+ working-directory: js+ - name: Deploy with wrangler+ run: bun run deploy-${{ inputs.environment || 'dev' }}+ env:+ CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}+ CLOUDFLARE_ACCOUNT_ID: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}+ working-directory: js/ai-editing-worker+concurrency:+ group: ${{ github.workflow }}-${{ inputs.environment || 'dev' }}+ cancel-in-progress: falsediff --git a/docker-compose.yml b/docker-compose.ymlindex a268978512..254c3064c6 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -423,7 +423,9 @@ services:- "8933:8933"volumes:- ./js:/app- - /app/ai-editing-worker/.wrangler+ # .wrangler (incl. the local D1 trace shard) persists to the host via the+ # ./js mount above, so `bun run traces --env local --local` works from the+ # host without docker exec. An anonymous volume used to shadow this path.depends_on:- sync_servicenetworks:diff --git a/js/ai-editing-worker/Dockerfile b/js/ai-editing-worker/Dockerfileindex 00934c37ce..d3706032b4 100644--- a/js/ai-editing-worker/Dockerfile+++ b/js/ai-editing-worker/Dockerfile@@ -8,4 +8,15 @@ ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crtWORKDIR /app/ai-editing-workerEXPOSE 8933-CMD ["sh", "-c", "bun scripts/generate-sandbox.ts && printf 'OPENAI_API_KEY=%s\\nANTHROPIC_API_KEY=%s\\nCEREBRAS_API_KEY=%s\\n' \"${OPENAI_API_KEY}\" \"${ANTHROPIC_API_KEY}\" \"${CEREBRAS_API_KEY}\" > .dev.vars && npx wrangler dev --env local --ip 0.0.0.0 --var SYNC_WS_BASE:ws://sync-service:8787"]+CMD ["sh", "-c", "\+ bun scripts/generate-sandbox.ts && \+ printf 'OPENAI_API_KEY=%s\\nANTHROPIC_API_KEY=%s\\nCEREBRAS_API_KEY=%s\\n' \+ \"${OPENAI_API_KEY}\" \+ \"${ANTHROPIC_API_KEY}\" \+ \"${CEREBRAS_API_KEY}\" \+ > .dev.vars && \+ npx wrangler dev \+ --env local \+ --ip 0.0.0.0 \+ --var SYNC_WS_BASE:ws://sync-service:8787\+"]diff --git a/js/ai-editing-worker/migrations/0001_create_edit_traces.sql b/js/ai-editing-worker/migrations/0001_create_edit_traces.sqlnew file mode 100644index 0000000000..ac4ad9948b--- /dev/null+++ b/js/ai-editing-worker/migrations/0001_create_edit_traces.sql@@ -0,0 +1,11 @@+-- Stores a markdown trace of every AI edit session, for after-the-fact+-- investigation (e.g. when a user reports a bad edit on some document).+CREATE TABLE IF NOT EXISTS edit_traces (+ id TEXT PRIMARY KEY,+ document_id TEXT NOT NULL,+ created_at INTEGER NOT NULL,+ markdown TEXT NOT NULL+);++CREATE INDEX IF NOT EXISTS idx_edit_traces_doc+ ON edit_traces (document_id, created_at DESC);diff --git a/js/ai-editing-worker/migrations/0002_trace_json.sql b/js/ai-editing-worker/migrations/0002_trace_json.sqlnew file mode 100644index 0000000000..666ce3b0ef--- /dev/null+++ b/js/ai-editing-worker/migrations/0002_trace_json.sql@@ -0,0 +1,3 @@+-- Traces are now stored as structured JSON (a serialized TraceSession) rather+-- than pre-rendered markdown; markdown is regenerated from the JSON on demand.+ALTER TABLE edit_traces RENAME COLUMN markdown TO trace_json;diff --git a/js/ai-editing-worker/package.json b/js/ai-editing-worker/package.jsonindex 6aa00186b1..7730ee348f 100644--- a/js/ai-editing-worker/package.json+++ b/js/ai-editing-worker/package.json@@ -5,7 +5,10 @@"type": "module","scripts": {"prebuild": "bun scripts/generate-sandbox.ts",- "type-check": "tsc --noEmit --project tsconfig.json"+ "type-check": "tsc --noEmit --project tsconfig.json",+ "traces": "bun scripts/traces.ts",+ "deploy-dev": "bun run prebuild && wrangler deploy --env dev",+ "deploy-prod": "bun run prebuild && wrangler deploy --env prod"},"dependencies": {"@ai-sdk/anthropic": "^3.0.85",diff --git a/js/ai-editing-worker/scripts/edit.ts b/js/ai-editing-worker/scripts/edit.tsindex ed668212ef..e448a0e01d 100644--- a/js/ai-editing-worker/scripts/edit.ts+++ b/js/ai-editing-worker/scripts/edit.ts@@ -9,6 +9,9 @@ const {"supervisor-model": supervisorModelFlag,"interpret-model": interpretModelFlag,"coding-model": codingModelFlag,+ "snippet-model": snippetModelFlag,+ "snippet-high-model": snippetHighModelFlag,+ interpret,debug,out,prompt: promptFlag,@@ -24,6 +27,9 @@ 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)" }).option("prompt-file", { type: "string", describe: "read the prompt from this file instead of --prompt" })@@ -73,7 +79,10 @@ 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,}),timeout: false,diff --git a/js/ai-editing-worker/scripts/traces.ts b/js/ai-editing-worker/scripts/traces.tsnew file mode 100644index 0000000000..8f2f886eb9--- /dev/null+++ b/js/ai-editing-worker/scripts/traces.ts@@ -0,0 +1,105 @@+#!/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 { 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 documentId = _[0] as string | undefined;+if (!documentId && !id) {+ 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}'`;+}++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>[];+}++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) {+ console.error("no matching trace");+ process.exit(1);+ }+ const raw = String(rows[0]!.trace_json);+ if (json) {+ process.stdout.write(raw);+ } else {+ process.stdout.write(+ renderTraceMarkdown(JSON.parse(raw) as TraceSession),+ );+ }+} 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) {+ console.error("no traces for that document");+ process.exit(1);+ }+ console.table(rows);+}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.tsnew file mode 100644index 0000000000..54fd482595--- /dev/null+++ b/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.test.ts@@ -0,0 +1,32 @@+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.tsnew file mode 100644index 0000000000..e4a0bdeecb--- /dev/null+++ b/js/ai-editing-worker/src/ai-editing/agents/coder-prompt.ts@@ -0,0 +1,32 @@+import type { SnippetSource } from '../runtime';++export function buildPrompt(+ task: string,+ context: string,+ snippets?: SnippetSource+): 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 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}`;+}diff --git a/js/ai-editing-worker/src/ai-editing/agents/coder.ts b/js/ai-editing-worker/src/ai-editing/agents/coder.tsindex 9482c4cebe..a5a0c7fba2 100644--- a/js/ai-editing-worker/src/ai-editing/agents/coder.ts+++ b/js/ai-editing-worker/src/ai-editing/agents/coder.ts@@ -3,11 +3,13 @@ import type { LexicalSession } from '../ai-toolkit';import API_COMPLETE from '../prompts/API_COMPLETE.md';import CODER from '../prompts/CODER.md';import SHARED from '../prompts/SHARED.md';+import { buildPrompt } from './coder-prompt';import {createImBlockedTool,createReadDocumentTool,createRunCodeTool,} from '../tools';+import { EDIT_PROVIDER_OPTIONS } from './model-options';import type { RunTaskDeps } from './types';export type { RunTaskDeps } from './types';@@ -39,6 +41,7 @@ export async function coder(sleep: deps.sleep,runner: deps.runner,onOps: deps.onOps,+ onRunCode: deps.onRunCode,}),readDocument: createReadDocumentTool({ session }),reportBlocked: createImBlockedTool(@@ -46,24 +49,8 @@ export async function coder(false),},+ providerOptions: EDIT_PROVIDER_OPTIONS,abortSignal: deps.signal,});}-function buildPrompt(- task: string,- context: string,- snippets?: Record<string, string>-): string {- const snippetBlock =- snippets && Object.keys(snippets).length > 0- ? [- '\n\nSnippets (access as `snippets.KEY` in your code -- do NOT re-embed as string literals):',- '```js',- `const snippets = \n${JSON.stringify(snippets, null, 2)}`,- '```',- ].join('\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}${contextBlock}`;-}diff --git a/js/ai-editing-worker/src/ai-editing/agents/index.ts b/js/ai-editing-worker/src/ai-editing/agents/index.tsindex 766898cef5..aeebe992ec 100644--- a/js/ai-editing-worker/src/ai-editing/agents/index.ts+++ b/js/ai-editing-worker/src/ai-editing/agents/index.ts@@ -1,4 +1,5 @@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/interpreter.ts b/js/ai-editing-worker/src/ai-editing/agents/interpreter.tsindex 0b43d8defe..3682006d63 100644--- a/js/ai-editing-worker/src/ai-editing/agents/interpreter.ts+++ b/js/ai-editing-worker/src/ai-editing/agents/interpreter.ts@@ -1,4 +1,5 @@import { generateText, type LanguageModel, stepCountIs, type Tool } from 'ai';+import { EDIT_PROVIDER_OPTIONS } from './model-options';export async function interpreter(documentContext: string,@@ -13,6 +14,7 @@ export async function interpreter(model,system,prompt,+ providerOptions: EDIT_PROVIDER_OPTIONS,...(tools ? { tools, stopWhen: stepCountIs(12) } : {}),});diff --git a/js/ai-editing-worker/src/ai-editing/agents/model-options.ts b/js/ai-editing-worker/src/ai-editing/agents/model-options.tsnew file mode 100644index 0000000000..433ad9ade4--- /dev/null+++ b/js/ai-editing-worker/src/ai-editing/agents/model-options.ts@@ -0,0 +1,7 @@+import type { AnthropicProviderOptions } from '@ai-sdk/anthropic';++export const EDIT_PROVIDER_OPTIONS = {+ anthropic: {+ thinking: { type: 'disabled' },+ } satisfies AnthropicProviderOptions,+};diff --git a/js/ai-editing-worker/src/ai-editing/agents/snippet.ts b/js/ai-editing-worker/src/ai-editing/agents/snippet.tsnew file mode 100644index 0000000000..6ad827f3bd--- /dev/null+++ b/js/ai-editing-worker/src/ai-editing/agents/snippet.ts@@ -0,0 +1,20 @@+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.ts b/js/ai-editing-worker/src/ai-editing/agents/supervisor.tsindex 43743036c2..3a42976071 100644--- a/js/ai-editing-worker/src/ai-editing/agents/supervisor.ts+++ b/js/ai-editing-worker/src/ai-editing/agents/supervisor.ts@@ -10,6 +10,8 @@ import { createDispatchTool, createImBlockedTool } from '../tools';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';@@ -31,13 +33,16 @@ export async function supervisor(const docContext = `<document>\n${initialText}\n</document>`;let intent = '';+ let interpretDurationMs: number | undefined;if (opts.interpret) {+ const interpretStartedAt = Date.now();const interpretation = await interpreter(docContext,request,models.interpret,INTERPRET_SYSTEM);+ interpretDurationMs = Date.now() - interpretStartedAt;tracker.add(models.interpret as { modelId: string },interpretation.totalUsage@@ -53,7 +58,10 @@ export async function supervisor(dispatch: createDispatchTool({session,childModel: models.coding,+ snippetModel: models.snippet,+ snippetHighModel: models.snippetHigh,tracker,+ runSnippet: snippet,params: opts.params,typingAnimations: opts.typingAnimations,sleep: opts.sleep,@@ -64,19 +72,31 @@ export async function supervisor(runner: opts.runner,onOps: opts.onOps,onCoderResult: opts.onCoderResult,+ onEditTrace: opts.onEditTrace,}),};const intentBlock = intent ? `<intent>\n${intent}\n</intent>\n\n` : '';const prompt = `Request: ${request}\n\n${intentBlock}${docContext}`;+ // Wall-clock duration of each supervisor step, measured between step+ // boundaries. Best-effort, but since between model calls it's probably good+ // enough.+ const stepDurationsMs: number[] = [];+ let lastStepAt = Date.now();const result = await generateText({model: models.supervisor,- stopWhen: [stepCountIs(6), hasToolCall('reportBlocked')],+ stopWhen: [stepCountIs(7), hasToolCall('reportBlocked')],system: MASTER_SYSTEM,prompt,tools,+ providerOptions: EDIT_PROVIDER_OPTIONS,abortSignal: opts.signal,+ onStepFinish: () => {+ const now = Date.now();+ stepDurationsMs.push(now - lastStepAt);+ lastStepAt = now;+ },});tracker.add(models.supervisor as { modelId: string }, result.totalUsage);@@ -90,7 +110,9 @@ export async function supervisor(text: result.text || 'Applied edits.',totalUsage: tracker,steps: result.steps,+ stepDurationsMs,intent,+ interpretDurationMs,clarification,};}diff --git a/js/ai-editing-worker/src/ai-editing/agents/types.ts b/js/ai-editing-worker/src/ai-editing/agents/types.tsindex c1b5cfa37c..672edd23a4 100644--- a/js/ai-editing-worker/src/ai-editing/agents/types.ts+++ b/js/ai-editing-worker/src/ai-editing/agents/types.ts@@ -2,19 +2,25 @@ import type { AwarenessSource } from '../awareness';import type { Doc } from '../doc';import type { DocumentOp } from '../editor';import type { DocumentOpQueueParams } from '../queue';-import type { RunCodeToolOptions, Writer } from '../tools';+import type { SnippetSource } from '../runtime';+import type {+ DispatchEditTrace,+ RunCodeToolOptions,+ Writer,+} from '../tools';export type RunTaskDeps = {doc: Doc;awarenessSource: AwarenessSource;runner: RunCodeToolOptions['runner'];context: string;- snippets?: Record<string, string>;+ snippets?: SnippetSource;params?: DocumentOpQueueParams;typingAnimations?: boolean;sleep?: (ms: number) => Promise<void>;signal?: AbortSignal;onOps?: RunCodeToolOptions['onOps'];+ onRunCode?: RunCodeToolOptions['onRunCode'];};export type RunAgentOptions = {@@ -28,4 +34,5 @@ export type RunAgentOptions = {signal?: AbortSignal;onOps?: (ops: DocumentOp[]) => void;onCoderResult?: (codes: string[][]) => void;+ onEditTrace?: (edits: DispatchEditTrace[]) => void;};diff --git a/js/ai-editing-worker/src/ai-editing/awareness/awareness-source.ts b/js/ai-editing-worker/src/ai-editing/awareness/awareness-source.tsindex cd5e73204e..94173c6d15 100644--- a/js/ai-editing-worker/src/ai-editing/awareness/awareness-source.ts+++ b/js/ai-editing-worker/src/ai-editing/awareness/awareness-source.ts@@ -21,44 +21,19 @@ import type { MarkdownLoroSchemaType } from '../../../../lexical-core/markdown-limport type { Awareness } from '../queue';export const AI_NAMES = [- 'Priya','Wolf',- 'Nora',- 'Finn','Teo',- 'Maya',- 'Hutch',- 'Omar','Julia',- 'Ravi',- 'Lena','Seamus',- 'Zoe',- 'Daniel',- 'Leo','Evan',- 'Soren',- 'Cleo','Gab',- 'Iris','Austin',- 'Theo','Peter',- 'Nadia',- 'Milo','Sean',- 'Mara',- 'Ethan',- 'Kai',- 'Luca',- 'Ava',- 'Jess','Eric',- 'Quinn',- 'Amara',- 'Juno',- 'Silas',- 'Noemi',+ 'Jacob',+ 'Aiden',+ 'Hutch',].map((n) => `${n} (AI)`);/** Palette names must resolve to `--color-<name>` (see collaboration/color.ts). */export const COLORS = [diff --git a/js/ai-editing-worker/src/ai-editing/prompts/SNIPPET.md b/js/ai-editing-worker/src/ai-editing/prompts/SNIPPET.mdnew file mode 100644index 0000000000..fc7430f0ab--- /dev/null+++ b/js/ai-editing-worker/src/ai-editing/prompts/SNIPPET.md@@ -0,0 +1,9 @@+# 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.mdindex 48662368e4..3b671ce71b 100644--- a/js/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md+++ b/js/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md@@ -15,8 +15,10 @@ Use the `<intent>` block as the resolved task. Apply it by calling `dispatch`. S## Instructions- Mention existing XML ids for the target region; dispatch expands context from those ids.-- Use `snippets` for all exact/verbatim text, including replacement strings, table cell contents, long text, code, and special-character text. In `editing_instruction`, refer to `snippets.KEY` instead of embedding the text. It is important you include all the necessary snippets since the writers will otherwise have to painstakingly type it out by hand.-- When creating new content from scratch (not editing existing text), generate the full text yourself and put it in `snippets`. Never ask the writer to invent or compose content -- writers are mechanical appliers, not content generators.+- 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.@@ -35,6 +37,7 @@ Use the `<intent>` block as the resolved task. Apply it by calling `dispatch`. S- 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.+- 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 Proceeddiff --git a/js/ai-editing-worker/src/ai-editing/queue/types.ts b/js/ai-editing-worker/src/ai-editing/queue/types.tsindex 1749b359f6..521f5883d2 100644--- a/js/ai-editing-worker/src/ai-editing/queue/types.ts+++ b/js/ai-editing-worker/src/ai-editing/queue/types.ts@@ -49,6 +49,6 @@ export const DEFAULT_RANGES: RandomRanges = {};export const DEFAULT_QUEUE_PARAMS: DocumentOpQueueParams = {- speed: 800,+ speed: 1200,ranges: DEFAULT_RANGES,};diff --git a/js/ai-editing-worker/src/ai-editing/runtime.test.ts b/js/ai-editing-worker/src/ai-editing/runtime.test.tsindex f519f9f3cc..591b3f24f5 100644--- a/js/ai-editing-worker/src/ai-editing/runtime.test.ts+++ b/js/ai-editing-worker/src/ai-editing/runtime.test.ts@@ -4,16 +4,21 @@ import { $getId } from '../../../lexical-core/plugins/nodeIdPlugin';import { mockAwarenessSource } from './awareness/awareness-source';import { Doc } from './doc/doc';import { DocumentEditor } from './editor/document-editor';-import { type CodeRunner, docIds, runEditorCode } from './runtime';+import {+ type CodeRunner,+ docIds,+ runEditorCode,+ type SnippetSource,+} from './runtime';// In-process executor for unit tests: the QuickJS sandbox's wasm import doesn't// resolve under bun test, so tests run the snippet via `new Function`. Production// always goes through `runInSandbox`. The id pool mirrors what the host injects.-const newFunctionRunner: CodeRunner = (validIds, code) => {+const newFunctionRunner: CodeRunner = (validIds, code, snippets) => {const refs = Array.from({ length: 128 }, (_, i) => `ref-${i + 1}`);const editor = new DocumentEditor({ validIds, refs });// eslint-disable-next-line no-new-func- new Function('editor', code)(editor);+ new Function('editor', 'snippets', code)(editor, snippets ?? {});return editor.drain();};@@ -38,7 +43,11 @@ function topIds(session: LexicalSession): string[] {}/** Run a snippet end-to-end (editor → ops → queue → real Doc), no timers/awareness delay. */-async function runCode(session: LexicalSession, code: string): Promise<string> {+async function runCode(+ session: LexicalSession,+ code: string,+ snippets?: SnippetSource+): Promise<string> {return runEditorCode({session,doc: new Doc(session),@@ -46,6 +55,7 @@ async function runCode(session: LexicalSession, code: string): Promise<string> {runner: newFunctionRunner,awarenessSource: mockAwarenessSource(),sleep: () => Promise.resolve(),+ snippets,});}@@ -100,6 +110,57 @@ describe('runtime — end to end against real Lexical', () => {});});+describe('runtime — snippet settling', () => {+ it('resolves pending snippets before the code runs', 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)+ ),+ },+ }+ );+ expect(summary).toBe('ok');+ expect(serializeWithXml(session)).toContain('composed later');+ });++ it('mixes verbatim strings and pending snippets', async () => {+ const { session, ids } = build('first');+ const summary = await runCode(+ session,+ `editor.insertParagraphAfter('${ids[0]}', snippets.a + ' ' + snippets.b);`,+ {+ a: 'verbatim',+ b: { brief: 'x', promise: Promise.resolve('pending') },+ }+ );+ expect(summary).toBe('ok');+ expect(serializeWithXml(session)).toContain('verbatim pending');+ });++ it('reports a failed snippet by key and applies nothing', 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')),+ },+ }+ );+ expect(summary).toBe('error: snippet "bad" failed: model unavailable');+ expect(serializeWithXml(session)).toBe(before);+ });+});+describe('runtime — awareness ref resolution', () => {it('points cursors at the inserted node, whose ref is its durable id', async () => {const { session, ids } = build('first');diff --git a/js/ai-editing-worker/src/ai-editing/runtime.ts b/js/ai-editing-worker/src/ai-editing/runtime.tsindex 2d4fcca5a9..70c06d1f3c 100644--- a/js/ai-editing-worker/src/ai-editing/runtime.ts+++ b/js/ai-editing-worker/src/ai-editing/runtime.ts@@ -33,13 +33,60 @@ 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);+}+export type RunEditorCodeArgs = {session: LexicalSession;doc: Doc;code: string;awarenessSource: AwarenessSource;runner: CodeRunner;- snippets?: Record<string, string>;+ snippets?: SnippetSource;params?: DocumentOpQueueParams;sleep?: (ms: number) => Promise<void>;/** Skip animation entirely -- apply each op directly with no typing, pauses, or cursor movement. */@@ -56,7 +103,8 @@ export type RunEditorCodeArgs = {export async function runEditorCode(args: RunEditorCodeArgs): Promise<string> {let ops: DocumentOp[];try {- ops = await args.runner(docIds(args.session), args.code, args.snippets);+ const snippets = await settleSnippets(args.snippets);+ ops = await args.runner(docIds(args.session), args.code, 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.tsindex 728eed57a7..868ad42f0f 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,5 +1,19 @@+import type { LanguageModel, LanguageModelUsage } from 'ai';import { describe, expect, it } from 'vitest';-import { computeContextRange, indexXmlRanges, mergeRanges } from './dispatch';+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,+ createDispatchTool,+ type DispatchEditTrace,+ indexXmlRanges,+ mergeRanges,+} from './dispatch';describe('mergeRanges', () => {it('leaves disjoint ranges alone', () => {@@ -100,3 +114,174 @@ describe('computeContextRange', () => {expect(range.endLine).toBe(3);});});++describe('dispatch — snippet_specs', () => {+ const usage: LanguageModelUsage = {+ inputTokens: 10,+ outputTokens: 5,+ totalTokens: 15,+ inputTokenDetails: {+ noCacheTokens: undefined,+ cacheReadTokens: undefined,+ cacheWriteTokens: undefined,+ },+ 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 };+ }++ 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' },+ },+ ],+ },+ 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(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+ );+ 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+ );+ 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' },+ ]);+ });++ 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');+ },+ });+ const out = await dispatchTool.execute?.(+ {+ edits: [+ {+ editing_instruction: 'do something else entirely',+ snippet_specs: { unused: 'never referenced' },+ },+ ],+ },+ callOptions+ );+ 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',+ });+ });+});diff --git a/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts b/js/ai-editing-worker/src/ai-editing/tools/dispatch.tsindex 8fb7dc2009..3674b00740 100644--- a/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts+++ b/js/ai-editing-worker/src/ai-editing/tools/dispatch.ts@@ -1,13 +1,20 @@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';@@ -191,10 +198,25 @@ 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. */+export type DispatchEditTrace = {+ snippets: SnippetTraceEntry[];+ coderStartedAt: number;+ coderFinishedAt: number;+ runCodeAt: number[];+};+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;runner: RunCodeToolOptions['runner'];params?: DocumentOpQueueParams;typingAnimations?: boolean;@@ -206,13 +228,18 @@ export type DispatchToolOptions = {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;};export function createDispatchTool(opts: DispatchToolOptions) {const {session,childModel,+ snippetModel,+ snippetHighModel,tracker,+ runSnippet,params,typingAnimations,sleep,@@ -222,6 +249,7 @@ export function createDispatchTool(opts: DispatchToolOptions) {runner,onOps,onCoderResult,+ onEditTrace,} = opts;const serialize = opts.serialize ?? serializeWithXml;return tool({@@ -240,6 +268,9 @@ export function createDispatchTool(opts: DispatchToolOptions) {.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'),@@ -249,30 +280,54 @@ export function createDispatchTool(opts: DispatchToolOptions) {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 }, i) => {- const writer = await makeWriter();- const { doc, awarenessSource } = writer;- try {- return await runTask(session, editing_instruction, childModel, {- doc,- awarenessSource,- context: xmlWindow(xml, contexts[i]!),- snippets,- params,- typingAnimations,- sleep,+ 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,- runner,- onOps,});- } finally {- writer.release();+ 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);diff --git a/js/ai-editing-worker/src/ai-editing/tools/index.ts b/js/ai-editing-worker/src/ai-editing/tools/index.tsindex 507522befb..53d47c0de0 100644--- a/js/ai-editing-worker/src/ai-editing/tools/index.ts+++ b/js/ai-editing-worker/src/ai-editing/tools/index.ts@@ -2,3 +2,4 @@ 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.tsindex 6b9ed87406..0e9ac1a592 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,18 +5,20 @@ import type { AwarenessSource } from '../awareness';import type { Doc } from '../doc';import type { DocumentOp } from '../editor';import type { DocumentOpQueueParams } from '../queue';-import { type CodeRunner, runEditorCode } from '../runtime';+import { type CodeRunner, runEditorCode, type SnippetSource } from '../runtime';export type RunCodeToolOptions = {session: LexicalSession;doc: Doc;awarenessSource: AwarenessSource;runner: CodeRunner;- snippets?: Record<string, string>;+ 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;};/** The writer's one tool: run a JS snippet against `editor`, returning compact@@ -28,6 +30,7 @@ export function createRunCodeTool(opts: RunCodeToolOptions) {"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?.();const result = await runEditorCode({session: opts.session,doc: opts.doc,diff --git a/js/ai-editing-worker/src/ai-editing/tools/snippets.ts b/js/ai-editing-worker/src/ai-editing/tools/snippets.tsnew file mode 100644index 0000000000..5827cb3406--- /dev/null+++ b/js/ai-editing-worker/src/ai-editing/tools/snippets.ts@@ -0,0 +1,89 @@+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.tsindex 5f46caeca8..07da50c64c 100644--- a/js/ai-editing-worker/src/endpoints/edit.ts+++ b/js/ai-editing-worker/src/endpoints/edit.ts@@ -10,6 +10,8 @@ import { type Bindings, getEnv } from '../env';import { type Model, runEditSession } from '../run-edit';import { runInSandbox } from '../sandbox';import { watchPresenceSpeed } from '../service-clients';+import { renderTraceMarkdown } from '../trace-log';+import { insertEditTrace } from '../traces-db';type Provider = 'anthropic' | 'cerebras' | 'openai';@@ -43,6 +45,11 @@ 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. */@@ -108,7 +115,7 @@ edit.post('/', zValidator('json', EditBody), async (c) => {setTimeout(resolve, ms / presence.multiplier()));- const { usage, ops, trace, clarification } = await runEditSession({+ const { usage, ops, session, clarification } = await runEditSession({wsUrl,documentId,prompt,@@ -116,6 +123,8 @@ 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,@@ -124,7 +133,28 @@ edit.post('/', zValidator('json', EditBody), async (c) => {runner: runInSandbox,signal,}).finally(presence.stop);- return c.json({ ok: true, usage, ops, trace, clarification });++ const db = c.env.TRACES_DB;+ if (db) {+ c.executionCtx.waitUntil(+ insertEditTrace(db, {+ id: session.sessionId,+ document_id: documentId,+ created_at: Date.now(),+ trace_json: JSON.stringify(session),+ }).catch((e) => {+ console.error('failed to persist edit trace:', e);+ })+ );+ }++ return c.json({+ ok: true,+ usage,+ ops,+ trace: debug ? renderTraceMarkdown(session) : undefined,+ clarification,+ });} catch (err) {if (!(err instanceof Error)) throw new Error(String(err));if (!signal.aborted) {diff --git a/js/ai-editing-worker/src/endpoints/index.ts b/js/ai-editing-worker/src/endpoints/index.tsindex a71aa42147..87c748ca62 100644--- a/js/ai-editing-worker/src/endpoints/index.ts+++ b/js/ai-editing-worker/src/endpoints/index.ts@@ -1,9 +1,11 @@import { Hono } from 'hono';import type { Bindings } from '../env';import edit from './edit';+import traces from './traces';const endpoints = new Hono<{ Bindings: Bindings }>();endpoints.route('/edit', edit);+endpoints.route('/traces', traces);export default endpoints;diff --git a/js/ai-editing-worker/src/endpoints/traces.ts b/js/ai-editing-worker/src/endpoints/traces.tsnew file mode 100644index 0000000000..82ef1ebc2d--- /dev/null+++ b/js/ai-editing-worker/src/endpoints/traces.ts@@ -0,0 +1,56 @@+import { Hono } from 'hono';+import { type Bindings, getEnv } from '../env';+import { deleteEditTracesByDocumentId, listEditTraces } from '../traces-db';++const traces = new Hono<{ Bindings: Bindings }>();++// Every trace holds full document content, so the whole surface is gated. Two+// callers are accepted: humans via `Authorization: Bearer <TRACE_ADMIN_KEY>`+// (e.g. the CLI), and internal services via `x-internal-auth-key:+// <INTERNAL_API_KEY>` (e.g. the delete-document worker purging traces).+traces.use('*', async (c, next) => {+ const env = getEnv(c.env);++ const bearer = (c.req.header('Authorization') ?? '').startsWith('Bearer ')+ ? (c.req.header('Authorization') ?? '').slice('Bearer '.length)+ : '';+ const adminOk =+ Boolean(env.TRACE_ADMIN_KEY) && bearer === env.TRACE_ADMIN_KEY;++ const internalKey = c.req.header('x-internal-auth-key') ?? '';+ const internalOk =+ Boolean(env.INTERNAL_API_KEY) && internalKey === env.INTERNAL_API_KEY;++ if (!env.TRACE_ADMIN_KEY && !env.INTERNAL_API_KEY) {+ return c.json({ error: 'traces endpoint not configured' }, 503);+ }+ if (!adminOk && !internalOk) {+ return c.json({ error: 'unauthorized' }, 401);+ }+ return next();+});++traces.get('/:documentId', async (c) => {+ const db = c.env.TRACES_DB;+ if (!db) return c.json({ error: 'traces db not bound' }, 503);+ const documentId = c.req.param('documentId');+ const rows = await listEditTraces(db, documentId);+ const results = rows.map((r) => ({+ id: r.id,+ createdAt: r.created_at,+ session: JSON.parse(r.trace_json) as unknown,+ }));+ return c.json({ documentId, count: results.length, traces: results });+});++// Called when a document is deleted so trace records (which hold full document+// content) don't outlive the document.+traces.delete('/:documentId', async (c) => {+ const db = c.env.TRACES_DB;+ if (!db) return c.json({ error: 'traces db not bound' }, 503);+ const documentId = c.req.param('documentId');+ await deleteEditTracesByDocumentId(db, documentId);+ return c.json({ documentId, deleted: true });+});++export default traces;diff --git a/js/ai-editing-worker/src/env.ts b/js/ai-editing-worker/src/env.tsindex d8cca29d38..546f785ffd 100644--- a/js/ai-editing-worker/src/env.ts+++ b/js/ai-editing-worker/src/env.ts@@ -1,23 +1,52 @@import { envsafe, str } from 'envsafe';+import type { D1Database } from './traces-db';export type Bindings = {ANTHROPIC_API_KEY: string | undefined;CEREBRAS_API_KEY: string | undefined;OPENAI_API_KEY: string | undefined;SYNC_WS_BASE: string;+ /** D1 database storing edit-session traces. Absent in envs without the binding. */+ TRACES_DB: D1Database | undefined;+ /** Shared admin key gating the trace-read endpoint; validated via getEnv. */+ TRACE_ADMIN_KEY: string | undefined;+ /** Org internal service-to-service key; accepted on the trace endpoints via+ * the `x-internal-auth-key` header (used by the delete-document worker). */+ INTERNAL_API_KEY: string | undefined;};export type Env = ReturnType<typeof validateEnv>;function validateEnv(rawEnv: Bindings) {+ const {+ ANTHROPIC_API_KEY,+ CEREBRAS_API_KEY,+ OPENAI_API_KEY,+ SYNC_WS_BASE,+ TRACE_ADMIN_KEY,+ INTERNAL_API_KEY,+ } = rawEnv;return envsafe({ANTHROPIC_API_KEY: str({ allowEmpty: false }),CEREBRAS_API_KEY: str({ allowEmpty: false }),OPENAI_API_KEY: str({ allowEmpty: false }),SYNC_WS_BASE: str({ allowEmpty: false }),+ // Empty when unset; the trace-read endpoint stays closed until it's set.+ TRACE_ADMIN_KEY: str({ default: '', allowEmpty: true }),+ // Empty when unset; internal-key trace access stays closed until it's set.+ INTERNAL_API_KEY: str({ default: '', allowEmpty: true }),},- { env: rawEnv as Record<string, string | undefined> }+ {+ env: {+ ANTHROPIC_API_KEY,+ CEREBRAS_API_KEY,+ OPENAI_API_KEY,+ SYNC_WS_BASE,+ TRACE_ADMIN_KEY,+ INTERNAL_API_KEY,+ },+ });}diff --git a/js/ai-editing-worker/src/run-edit.ts b/js/ai-editing-worker/src/run-edit.tsindex cfca91d704..f30a58d79a 100644--- a/js/ai-editing-worker/src/run-edit.ts+++ b/js/ai-editing-worker/src/run-edit.ts@@ -8,12 +8,13 @@ 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 { CodeRunner } from './ai-editing/runtime';import type { UsageEntry } from './ai-editing/token-tracker';import { serializeWithXml } from './ai-editing/utils';import { EditingWorkspace } from './editing-workspace';import { createWorkerSyncSource } from './sources';-import { buildTraceLog } from './trace-log';+import { buildTraceSession, type TraceSession } from './trace-log';export type Model = {provider: 'anthropic' | 'cerebras' | 'openai';@@ -30,6 +31,9 @@ export type ResolvedModels = {supervisor: LanguageModel;interpret: LanguageModel;coding: LanguageModel;+ snippet: LanguageModel;+ /** Stronger composition model for `effort: "high"` snippet specs. */+ snippetHigh: LanguageModel;};export type RunEditArgs = {@@ -54,7 +58,8 @@ export type { UsageEntry };export type RunEditResult = {usage: UsageEntry[];ops: DocumentOp[];- trace?: string;+ /** Structured trace of the session; stored as JSON, rendered to markdown on demand. */+ session: TraceSession;clarification?: string;};@@ -99,24 +104,30 @@ export async function runEditSession(const allOps: DocumentOp[] = [];// code, per coder, per batchconst coderCodeBlocks: string[][][] = [];+ // snippet + timing traces, per edit, per batch+ const dispatchEditTraces: DispatchEditTrace[][] = [];+ const sessionId = crypto.randomUUID();const startedAt = new Date();const initialDocument = serializeWithXml(workspace.session);try {- const { totalUsage, steps, intent, clarification } = await supervisor(- workspace.session,- args.prompt,- args.models,- {- borrowWriter: () => workspace.borrowWriter(),- typingAnimations: args.typingAnimations,- sleep: args.sleep,- signal: args.signal,- interpret: args.interpret,- runner: args.runner,- onOps: (ops) => allOps.push(...ops),- onCoderResult: (codes) => coderCodeBlocks.push(codes),- }- );+ const {+ totalUsage,+ steps,+ stepDurationsMs,+ intent,+ interpretDurationMs,+ clarification,+ } = await supervisor(workspace.session, args.prompt, args.models, {+ borrowWriter: () => workspace.borrowWriter(),+ typingAnimations: args.typingAnimations,+ sleep: args.sleep,+ signal: args.signal,+ interpret: args.interpret,+ runner: args.runner,+ onOps: (ops) => allOps.push(...ops),+ onCoderResult: (codes) => coderCodeBlocks.push(codes),+ onEditTrace: (edits) => dispatchEditTraces.push(edits),+ });// Drain the queued propagates (plus a final catch-all sync) and ensure every// commit reached the server before we disconnect.@@ -125,25 +136,27 @@ export async function runEditSession(const usage = totalUsage.toEntries();- const trace = buildTraceLog(+ const session = buildTraceSession({+ sessionId,documentId: args.documentId,prompt: args.prompt,startedAt,initialDocument,intent,+ interpretDurationMs,coderCodeBlocks,+ dispatchEditTraces,+ stepDurationsMs,},steps as any,usage);- console.log(JSON.stringify({ documentId: args.documentId, debug: trace }));-return {usage,ops: allOps,- trace: args.debug ? trace : undefined,+ session,clarification,};} finally {diff --git a/js/ai-editing-worker/src/trace-log.ts b/js/ai-editing-worker/src/trace-log.tsindex b05e4ba9c8..576d03f410 100644--- a/js/ai-editing-worker/src/trace-log.ts+++ b/js/ai-editing-worker/src/trace-log.ts@@ -1,27 +1,109 @@import type { StepResult, ToolSet } from 'ai';import type { UsageEntry } from './ai-editing/token-tracker';+import type { DispatchEditTrace } from './ai-editing/tools';+/** Raw inputs collected during a run, normalized into a TraceSession. */export type TraceMeta = {+ sessionId: string;documentId: string;prompt: string;startedAt: Date;initialDocument?: string;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[][][];+ /** Snippet + timing traces, indexed by dispatch round then edit index. */+ dispatchEditTraces?: DispatchEditTrace[][];+ /** Wall-clock duration of each supervisor step, in ms. */+ stepDurationsMs?: number[];};type Usage = UsageEntry[];+export type TraceToolCall = {+ toolName: string;+ input: unknown;+ output: unknown;+};++export type TraceStep = {+ text?: string;+ durationMs?: number;+ inputTokens: number;+ outputTokens: number;+ toolCalls: TraceToolCall[];+};++/** Structured, serializable record of an edit session — the stored source of+ * truth. Markdown is rendered from it on demand via renderTraceMarkdown. */+export type TraceSession = {+ version: 1;+ sessionId: string;+ documentId: string;+ prompt: string;+ startedAt: string;+ initialDocument?: string;+ intent?: string;+ interpretDurationMs?: number;+ steps: TraceStep[];+ usage: Usage;+ coderCodeBlocks?: string[][][];+ dispatchEditTraces?: DispatchEditTrace[][];+};++/** Normalize the AI SDK's rich step objects into the serializable session. */+export function buildTraceSession(+ meta: TraceMeta,+ steps: StepResult<ToolSet>[],+ usage: Usage+): TraceSession {+ return {+ version: 1,+ sessionId: meta.sessionId,+ documentId: meta.documentId,+ prompt: meta.prompt,+ startedAt: meta.startedAt.toISOString(),+ initialDocument: meta.initialDocument,+ intent: meta.intent,+ interpretDurationMs: meta.interpretDurationMs,+ steps: steps.map((step, i) => ({+ text: step.text || undefined,+ durationMs: meta.stepDurationsMs?.[i],+ inputTokens: step.usage.inputTokens ?? 0,+ outputTokens: step.usage.outputTokens ?? 0,+ toolCalls: step.toolCalls.map((call, j) => ({+ toolName: call.toolName,+ input: call.input,+ output: (step.toolResults?.[j] as { output?: unknown } | undefined)+ ?.output,+ })),+ })),+ usage,+ coderCodeBlocks: meta.coderCodeBlocks,+ dispatchEditTraces: meta.dispatchEditTraces,+ };+}++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`. */+function relTime(ms: number | undefined, t0: number | undefined): string {+ if (ms == null || t0 == null) return '?';+ return `t+${((ms - t0) / 1000).toFixed(1)}s`;+}+function formatDispatchArgs(- args: {- edits: Array<{- editing_instruction: string;- context?: { start_line: number; end_line: number };- snippets?: Record<string, string>;- }>;- },- codesPerEdit?: string[][]+ args: { edits: TraceDispatchEdit[] },+ codesPerEdit?: string[][],+ editTraces?: DispatchEditTrace[],+ t0?: number): string {return args.edits.map((e, i) => {@@ -31,12 +113,40 @@ function formatDispatchArgs(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)) {- out += `\n snippets.${key}:\n \`\`\`\n${value+ 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) {@@ -52,23 +162,19 @@ function formatDispatchArgs(}function formatToolCall(- call: { toolName: string; input: unknown },- output: unknown,- codesPerEdit?: string[][]+ call: TraceToolCall,+ codesPerEdit?: string[][],+ editTraces?: DispatchEditTrace[],+ t0?: number): string {const lines: string[] = [];+ const { output } = call;if (call.toolName === 'dispatch') {- const { edits } = call.input as {- edits: Array<{- editing_instruction: string;- context?: { start_line: number; end_line: number };- snippets?: Record<string, string>;- }>;- };+ const { edits } = call.input as { edits: TraceDispatchEdit[] };lines.push(`**dispatch** — ${edits.length} edit(s)`);lines.push('');- lines.push(formatDispatchArgs({ edits }, codesPerEdit));+ lines.push(formatDispatchArgs({ edits }, codesPerEdit, editTraces, t0));if (output != null) {const res = String(output);const docStart = res.indexOf('<document>');@@ -111,80 +217,102 @@ function formatToolCall(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: StepResult<ToolSet>,+ step: TraceStep,i: number,+ elapsedMs: number | undefined,dispatchRoundRef: { current: number },- coderCodeBlocks?: string[][][]+ coderCodeBlocks?: string[][][],+ dispatchEditTraces?: DispatchEditTrace[][],+ t0?: number): string {- const lines: string[] = [`### Step ${i + 1}`];+ const lines: string[] = [+ `### Step ${i + 1}${formatTiming(step.durationMs, elapsedMs)}`,+ ];if (step.text) {lines.push('');lines.push(step.text.trim());}- for (let j = 0; j < step.toolCalls.length; j++) {- const call = step.toolCalls[j]!;- const result = step.toolResults?.[j];- const codesPerEdit =- call.toolName === 'dispatch'- ? coderCodeBlocks?.[dispatchRoundRef.current++]- : undefined;+ 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 as unknown as { toolName: string; input: unknown },- result != null- ? (result as unknown as { output: unknown }).output- : undefined,- codesPerEdit- )- );+ lines.push(formatToolCall(call, codesPerEdit, editTraces, t0));}- const { inputTokens, outputTokens } = step.usage;lines.push('');lines.push(- `*${inputTokens.toLocaleString()} in / ${outputTokens.toLocaleString()} out*`+ `*${step.inputTokens.toLocaleString()} in / ${step.outputTokens.toLocaleString()} out*`);return lines.join('\n');}-function formatTrace(- meta: TraceMeta,- steps: StepResult<ToolSet>[],- usage: Usage-): string {+/** Render the stored session into the human-readable markdown trace. */+export function renderTraceMarkdown(session: TraceSession): string {const sections: string[] = ['# AI Edit Trace',- `- **document:** ${meta.documentId}`,- `- **timestamp:** ${meta.startedAt.toISOString()}`,- `- **prompt:** ${meta.prompt}`,+ `- **document:** ${session.documentId}`,+ `- **timestamp:** ${session.startedAt}`,+ `- **prompt:** ${session.prompt}`,];- if (meta.initialDocument) {+ if (session.initialDocument) {sections.push('','**document before:**','```xml',- meta.initialDocument,+ session.initialDocument,'```');}- if (meta.intent) {- sections.push('', '---', '', '## Interpreter', '', meta.intent);+ if (session.intent) {+ sections.push(+ '',+ '---',+ '',+ `## Interpreter${formatTiming(session.interpretDurationMs)}`,+ '',+ session.intent+ );}sections.push('', '---', '', '## Supervisor');const dispatchRoundRef = { current: 0 };- for (let i = 0; i < steps.length; i++) {+ const t0 = Date.parse(session.startedAt);+ let elapsedMs = 0;+ let sawDuration = false;+ 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(steps[i]!, i, dispatchRoundRef, meta.coderCodeBlocks)+ formatStep(+ step,+ i,+ sawDuration ? elapsedMs : undefined,+ dispatchRoundRef,+ session.coderCodeBlocks,+ session.dispatchEditTraces,+ Number.isNaN(t0) ? undefined : t0+ ));}@@ -196,7 +324,7 @@ function formatTrace('| model | input | output |','|---|---|---|');- for (const u of usage) {+ for (const u of session.usage) {sections.push(`| ${u.model} | ${u.inputTokens.toLocaleString()} | ${u.outputTokens.toLocaleString()} |`);@@ -204,11 +332,3 @@ function formatTrace(return sections.join('\n');}--export function buildTraceLog(- meta: TraceMeta,- steps: StepResult<ToolSet>[],- usage: Usage-): string {- return formatTrace(meta, steps, usage);-}diff --git a/js/ai-editing-worker/src/traces-db.ts b/js/ai-editing-worker/src/traces-db.tsnew file mode 100644index 0000000000..b03436e26e--- /dev/null+++ b/js/ai-editing-worker/src/traces-db.ts@@ -0,0 +1,55 @@+// The narrow slice of the Cloudflare D1 API we use, declared locally so this+// worker doesn't need `@cloudflare/workers-types` wired into its tsconfig.+export interface D1Database {+ prepare(query: string): D1PreparedStatement;+}+interface D1PreparedStatement {+ bind(...values: unknown[]): D1PreparedStatement;+ run(): Promise<unknown>;+ all<T>(): Promise<{ results: T[] }>;+}++export type EditTrace = {+ id: string;+ document_id: string;+ created_at: number;+ /** Serialized TraceSession (see trace-log.ts). */+ trace_json: string;+};++export async function insertEditTrace(+ db: D1Database,+ trace: EditTrace+): Promise<void> {+ await db+ .prepare(+ 'INSERT INTO edit_traces (id, document_id, created_at, trace_json) VALUES (?, ?, ?, ?)'+ )+ .bind(trace.id, trace.document_id, trace.created_at, trace.trace_json)+ .run();+}++/** Delete every trace for a document. Returns silently if there are none. */+export async function deleteEditTracesByDocumentId(+ db: D1Database,+ documentId: string+): Promise<void> {+ await db+ .prepare('DELETE FROM edit_traces WHERE document_id = ?')+ .bind(documentId)+ .run();+}++/** All traces for a document, newest first. */+export async function listEditTraces(+ db: D1Database,+ documentId: string+): Promise<EditTrace[]> {+ const { results } = await db+ .prepare(+ 'SELECT id, document_id, created_at, trace_json FROM edit_traces WHERE document_id = ? ORDER BY created_at DESC'+ )+ .bind(documentId)+ .all<EditTrace>();+ return results;+}diff --git a/js/ai-editing-worker/wrangler.toml b/js/ai-editing-worker/wrangler.tomlindex 1373900b6a..e8ad4d60c0 100644--- a/js/ai-editing-worker/wrangler.toml+++ b/js/ai-editing-worker/wrangler.toml@@ -23,6 +23,11 @@ fallthrough = true[observability]enabled = true+[[d1_databases]]+binding = "TRACES_DB"+database_name = "ai-editing-traces"+database_id = "16d34e99-3bc6-44e4-a287-1ea65183bd28"+[vars]SYNC_WS_BASE = "wss://sync-service-prod2.macroverse.workers.dev"DSS_BASE = "https://cloud-storage.macro.com"@@ -40,6 +45,12 @@ SEARCH_SERVICE_BASE = "http://search-processing-service:8080"CONTACTS_SERVICE_BASE = "http://contacts-service:8080"AUTH_SERVICE_BASE = "http://connection-gateway:8080"+# Local dev uses an on-disk SQLite shard, so the id is only a reference.+[[env.local.d1_databases]]+binding = "TRACES_DB"+database_name = "ai-editing-traces"+database_id = "16d34e99-3bc6-44e4-a287-1ea65183bd28"+[env.dev.vars]SYNC_WS_BASE = "wss://sync-service-dev3.macroverse.workers.dev"DSS_BASE = "https://cloud-storage-dev.macro.com"@@ -47,6 +58,11 @@ SEARCH_SERVICE_BASE = "https://cloud-storage-dev.macro.com"CONTACTS_SERVICE_BASE = "https://contacts-dev.macro.com"AUTH_SERVICE_BASE = "https://auth-service-dev.macro.com"+[[env.dev.d1_databases]]+binding = "TRACES_DB"+database_name = "ai-editing-traces"+database_id = "16d34e99-3bc6-44e4-a287-1ea65183bd28"+[env.playground]name = "ai-editing-worker-playground"@@ -57,6 +73,11 @@ SEARCH_SERVICE_BASE = "https://cloud-storage-dev.macro.com"CONTACTS_SERVICE_BASE = "https://contacts-dev.macro.com"AUTH_SERVICE_BASE = "https://auth-service-dev.macro.com"+[[env.playground.d1_databases]]+binding = "TRACES_DB"+database_name = "ai-editing-traces-playground"+database_id = "28cdeacb-6468-449b-a1c7-a193b220501e"+[env.prod]name = "ai-editing-worker"@@ -66,3 +87,8 @@ DSS_BASE = "https://cloud-storage.macro.com"SEARCH_SERVICE_BASE = "https://cloud-storage.macro.com"CONTACTS_SERVICE_BASE = "https://contacts.macro.com"AUTH_SERVICE_BASE = "https://auth-service.macro.com"++[[env.prod.d1_databases]]+binding = "TRACES_DB"+database_name = "ai-editing-traces-prod"+database_id = "2af569f1-2edb-4e6a-99a2-f2f9ee82c0d1"diff --git a/rust/cloud-storage/document_storage_service/src/main.rs b/rust/cloud-storage/document_storage_service/src/main.rsindex 712019da8e..504633c6ce 100644--- a/rust/cloud-storage/document_storage_service/src/main.rs+++ b/rust/cloud-storage/document_storage_service/src/main.rs@@ -72,7 +72,9 @@ use macro_auth::middleware::decode_jwt::JwtValidationArgs;use macro_entrypoint::MacroEntrypoint;use macro_env_var::maybe_env_vars;use macro_event_broker::{KafkaEventPublisher, MacroEventBrokerService};-use macro_service_urls::{ConnectionGatewayUrl, LexicalServiceUrl, SyncServiceUrl};+use macro_service_urls::{+ AiEditingWorkerUrl, ConnectionGatewayUrl, LexicalServiceUrl, SyncServiceUrl,+};use macro_sha_count_client::Redis;use notification::domain::service::SqsNotificationIngress;#[cfg(feature = "graphql")]@@ -768,6 +770,13 @@ async fn main() -> anyhow::Result<()> {#[cfg(feature = "delete_document_worker")]{+ let editing_worker_client = Arc::new(+ documents_hex::outbound::editing_worker_client::ReqwestEditingWorkerClient::from_url(+ AiEditingWorkerUrl::new()?.to_string(),+ )+ .with_internal_auth_key(Some(api_context.config.internal_api_key.to_string())),+ );+// Spawn the delete document worker.let delete_worker_ctx = service::delete_document_worker::DeleteDocumentWorkerContext {worker: Arc::new(delete_document_worker),@@ -775,6 +784,7 @@ async fn main() -> anyhow::Result<()> {s3_client: api_context.s3_client.clone(),redis_client: api_context.redis_client.clone(),sync_service_client: api_context.sync_service_client.clone(),+ editing_worker_client,};tokio::spawn(async move {diff --git a/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/handle.rs b/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/handle.rsindex 2555aee612..f83cd75c83 100644--- a/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/handle.rs+++ b/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/handle.rs@@ -1,4 +1,5 @@use anyhow::Context;+use documents_hex::domain::ports::editing::EditingWorkerService;use models_properties::{EntityReference, EntityType};use properties_db_client::entity_properties::delete as entity_properties_delete;@@ -99,6 +100,15 @@ pub async fn handle(tracing::trace!(error=?e, "could not delete file from sync service");});+ // Delete AI edit traces (they hold full document content)+ let _ = ctx+ .editing_worker_client+ .delete_traces(document_id)+ .await+ .inspect_err(|e| {+ tracing::trace!(error=?e, "could not delete ai edit traces");+ });+// Delete document propertiestracing::trace!(document_id=%document_id, "deleting document properties");diff --git a/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/mod.rs b/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/mod.rsindex 5385144fda..99244a089f 100644--- a/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/mod.rs+++ b/rust/cloud-storage/document_storage_service/src/service/delete_document_worker/mod.rs@@ -1,5 +1,6 @@use std::sync::Arc;+use documents_hex::outbound::editing_worker_client::ReqwestEditingWorkerClient;use macro_sha_count_client::Redis;use sync_service_client::SyncServiceClient;@@ -17,6 +18,7 @@ pub struct DeleteDocumentWorkerContext {pub s3_client: Arc<S3>,pub redis_client: Arc<Redis>,pub sync_service_client: Arc<SyncServiceClient>,+ pub editing_worker_client: Arc<ReqwestEditingWorkerClient>,}/// Runs the delete document worker in an infinite loop, restarting on failure.diff --git a/rust/cloud-storage/documents/src/domain/ports/editing.rs b/rust/cloud-storage/documents/src/domain/ports/editing.rsindex f46022f6cd..5583254165 100644--- a/rust/cloud-storage/documents/src/domain/ports/editing.rs+++ b/rust/cloud-storage/documents/src/domain/ports/editing.rs@@ -35,4 +35,9 @@ pub trait EditingWorkerService: Send + Sync + 'static {document_token: &DocumentPermissionToken,instructions: &str,) -> impl Future<Output = anyhow::Result<EditResult>> + Send;++ /// Delete all AI edit trace records for `document_id`. Called during+ /// document deletion so traces (which hold full document content) don't+ /// outlive the document.+ fn delete_traces(&self, document_id: &str) -> impl Future<Output = anyhow::Result<()>> + Send;}diff --git a/rust/cloud-storage/documents/src/outbound/editing_worker_client.rs b/rust/cloud-storage/documents/src/outbound/editing_worker_client.rsindex 8351b1bd20..f52d1ac534 100644--- a/rust/cloud-storage/documents/src/outbound/editing_worker_client.rs+++ b/rust/cloud-storage/documents/src/outbound/editing_worker_client.rs@@ -10,18 +10,29 @@ use std::sync::Arc;pub struct ReqwestEditingWorkerClient {worker_url: String,client: Arc<Client>,+ internal_auth_key: Option<String>,}impl ReqwestEditingWorkerClient {/// Construct a new client.pub fn new(worker_url: String, client: Arc<Client>) -> Self {- Self { worker_url, client }+ Self {+ worker_url,+ client,+ internal_auth_key: None,+ }}/// Construct a client backed by a fresh default reqwest client.pub fn from_url(worker_url: String) -> Self {Self::new(worker_url, Arc::new(Client::new()))}++ /// Set the internal auth key used to authenticate `delete_traces` calls.+ pub fn with_internal_auth_key(mut self, internal_auth_key: Option<String>) -> Self {+ self.internal_auth_key = internal_auth_key;+ self+ }}impl EditingWorkerService for ReqwestEditingWorkerClient {@@ -41,7 +52,7 @@ impl EditingWorkerService for ReqwestEditingWorkerClient {// or down."models": {"supervisor": [- { "provider": "anthropic", "model": "claude-sonnet-4-6" },+ { "provider": "anthropic", "model": "claude-opus-4-8" },{ "provider": "openai", "model": "gpt-5.5" },],"interpret": [@@ -52,8 +63,19 @@ impl EditingWorkerService for ReqwestEditingWorkerClient {{ "provider": "cerebras", "model": "gpt-oss-120b" },{ "provider": "anthropic", "model": "claude-haiku-4-5" },],+ // Snippet composition: fast/cheap by default, escalating to a+ // strong prose model when the supervisor marks a spec+ // `effort: "high"`.+ "snippet": [+ { "provider": "cerebras", "model": "gpt-oss-120b" },+ { "provider": "anthropic", "model": "claude-haiku-4-5" },+ ],+ "snippetHigh": [+ { "provider": "anthropic", "model": "claude-sonnet-4-6" },+ { "provider": "cerebras", "model": "gpt-oss-120b" },+ ],},- "interpret": true,+ "interpret": false,});let edit_resp = self@@ -96,4 +118,26 @@ impl EditingWorkerService for ReqwestEditingWorkerClient {clarification: body["clarification"].as_str().map(str::to_owned),})}++ #[tracing::instrument(skip_all, fields(document_id), err)]+ async fn delete_traces(&self, document_id: &str) -> anyhow::Result<()> {+ let Some(internal_auth_key) = self.internal_auth_key.as_deref() else {+ anyhow::bail!("editing worker client has no internal auth key configured");+ };++ let resp = self+ .client+ .delete(format!("{}/traces/{}", self.worker_url, document_id))+ .header("x-internal-auth-key", internal_auth_key)+ .send()+ .await?;++ let status = resp.status();+ if !status.is_success() {+ let body = resp.text().await.unwrap_or_default();+ anyhow::bail!("editing worker returned {}: {}", status, body);+ }++ Ok(())+ }}diff --git a/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/deploy_ai_editing_worker.rs b/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/deploy_ai_editing_worker.rsnew file mode 100644index 0000000000..368263507b--- /dev/null+++ b/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/deploy_ai_editing_worker.rs@@ -0,0 +1,86 @@+//! `Deploy AI Editing Worker` — deploys the `ai-editing-worker` Cloudflare+//! Worker (`js/ai-editing-worker`) via wrangler. Generated into+//! `deploy_ai_editing_worker.yml`.+//!+//! Push to `main` (path-gated) auto-deploys `dev`; `workflow_dispatch` picks the+//! target env via a `string` input (`dev` or `prod`, defaults to `dev`). Runs on+//! the small profile — a bun install plus `wrangler deploy`, no Nix or cache+//! volume needed.++use std::collections::HashMap;++use gh_workflow::{+ Concurrency, Event, Expression, Job, Push, Run, Step, Use, Workflow, WorkflowDispatch,+ WorkflowDispatchInput,+};++use crate::workflows::{runners, steps, vars};++/// Build the workflow.+pub fn deploy_ai_editing_worker() -> Workflow {+ Workflow::new("Deploy AI Editing Worker")+ .on(Event::default()+ // Only redeploy when the worker or something it bundles changes.+ // Paths mirror the wrangler aliases in+ // `js/ai-editing-worker/wrangler.toml`.+ .push(+ Push::default()+ .add_branch("main")+ .add_path(".github/workflows/deploy_ai_editing_worker.yml")+ .add_path("js/bun.lock")+ .add_path("js/package.json")+ .add_path("js/ai-editing-worker/**")+ .add_path("js/app/packages/core/**")+ .add_path("js/app/packages/websocket/**")+ .add_path("js/loro-mirror/**"),+ )+ .workflow_dispatch(WorkflowDispatch::default().inputs(HashMap::from([(+ "environment".to_string(),+ // Struct literal, not the builder: the `Setters`-derived+ // `default` setter collides with `Default::default()`.+ WorkflowDispatchInput {+ description: "Environment to deploy (dev or prod)".to_string(),+ required: false,+ input_type: "string".to_string(),+ default: Some("dev".to_string()),+ },+ )]))))+ .concurrency(+ Concurrency::new(Expression::new(+ "${{ github.workflow }}-${{ inputs.environment || 'dev' }}",+ ))+ .cancel_in_progress(false),+ )+ .add_job("deploy", deploy())+}++fn deploy() -> Job {+ Job::default()+ .name("Deploy to Cloudflare")+ .runs_on(runners::Runner::Small.to_string())+ .add_step(steps::checkout(false, false))+ .add_step(setup_bun())+ .add_step(install_deps())+ .add_step(deploy_step())+}++fn setup_bun() -> Step<Use> {+ Step::new("Setup Bun").uses("oven-sh", "setup-bun", "v2")+}++fn install_deps() -> Step<Run> {+ Step::new("Install dependencies")+ .run("bun install --frozen-lockfile")+ .working_directory("js")+}++fn deploy_step() -> Step<Run> {+ // On push, `inputs.environment` is empty, so this deploys `dev`. Manual+ // dispatch picks dev or prod. `deploy-<env>` regenerates the sandbox before+ // `wrangler deploy` (see js/ai-editing-worker/package.json).+ Step::new("Deploy with wrangler")+ .run("bun run deploy-${{ inputs.environment || 'dev' }}")+ .working_directory("js/ai-editing-worker")+ .add_env(("CLOUDFLARE_API_TOKEN", vars::CLOUDFLARE_API_TOKEN))+ .add_env(("CLOUDFLARE_ACCOUNT_ID", vars::CLOUDFLARE_ACCOUNT_ID))+}diff --git a/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/mod.rs b/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/mod.rsindex 551ded7fce..87629de3d3 100644--- a/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/mod.rs+++ b/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/mod.rs@@ -22,6 +22,7 @@ mod check_node_modules_nix;mod cleanup_preview;mod code_check_cloud_storage;mod code_check_infra;+mod deploy_ai_editing_worker;mod deploy_preview;mod deploy_web_app;mod deploy_web_app_dev_push;@@ -148,6 +149,11 @@ const WORKFLOWS: &[WorkflowFile] = &[file_name: "code_check_cloud_storage.yml",render_yaml: || render_gh_workflow(code_check_cloud_storage::code_check_cloud_storage)(),},+ WorkflowFile {+ slug: "deploy_ai_editing_worker",+ file_name: "deploy_ai_editing_worker.yml",+ render_yaml: || render_gh_workflow(deploy_ai_editing_worker::deploy_ai_editing_worker)(),+ },WorkflowFile {slug: "deploy_preview",file_name: "deploy_preview.yml",diff --git a/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/vars.rs b/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/vars.rsindex 19dbefbc5e..b7ab1c8aaf 100644--- a/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/vars.rs+++ b/rust/cloud-storage/tools/xtask/crates/xtask_workflows/src/workflows/vars.rs@@ -14,6 +14,7 @@ macro_rules! secret {secret!(AWS_ACCESS_KEY);secret!(AWS_SECRET_ACCESS_KEY);secret!(CACHIX_AUTH_TOKEN);+secret!(CLOUDFLARE_API_TOKEN);secret!(DD_API_KEY);secret!(DD_APP_KEY);secret!(DD_WEB_APP_TOKEN);@@ -25,6 +26,10 @@ secret!(PULUMI_ACCESS_TOKEN);secret!(SEGMENT_WRITE_KEY);secret!(SEGMENT_WRITE_KEY_PRODUCTION);+/// Cloudflare account id. A repo *variable* (not a secret), matching the+/// hand-written `deploy-lexical-service.yml`.+pub const CLOUDFLARE_ACCOUNT_ID: &str = "${{ vars.CLOUDFLARE_ACCOUNT_ID }}";+/// Nextest thread count for the test job. Tuned for the previous/// `linux-extra-beefy` runner; revisit if `namespace-profile-linux-mid` is/// smaller.