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.

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.yml
new file mode 100644
index 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: false
diff --git a/docker-compose.yml b/docker-compose.yml
index 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_service
networks:
diff --git a/js/ai-editing-worker/Dockerfile b/js/ai-editing-worker/Dockerfile
index 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.crt
WORKDIR /app/ai-editing-worker
EXPOSE 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.sql
new file mode 100644
index 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.sql
new file mode 100644
index 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.json
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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-l
import 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.md
new file mode 100644
index 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.md
index 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 Proceed
diff --git a/js/ai-editing-worker/src/ai-editing/queue/types.ts b/js/ai-editing-worker/src/ai-editing/queue/types.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 batch
const 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.ts
index 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.ts
new file mode 100644
index 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.toml
index 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.rs
index 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.rs
index 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 properties
tracing::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.rs
index 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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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.