Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
ai-editing-worker
What it is
Part of Documents' AI editing feature — a Cloudflare Worker that joins a
document as a real Loro collaboration peer and streams AI-driven edits
through it. AI_EDITING.md has the full flow (interpreter/supervisor/writer
agents, the QuickJS sandbox → DocumentOp[] → animation pipeline). Read it
before touching the edit flow.
Start here
src/index.ts/src/endpoints/index.ts: the hono app and route table (POST /editand friends).src/run-edit.ts:runEditSession— joins the sync-service WebSocket, drives the agents, flushes commits back.src/canvas/: bounded CanvasEditor SDK, real QuickJS runner, live graphics/Loro session, supervised writers, renderer-based text fitting, vision reads and concurrency/acknowledgement tests.direct.tsruns main-agent SDK batches through the same guarded apply path without another model.browser.tsleases reset remote pages using fresh request-owned CDP connections;cache.tsstores only bounded cloned values, never cross-request sockets or promises.render.tsuses the configured browser and the read-only webcanvas-render.htmlbundle;text-layout.tsrevalidates asynchronous measurements before the atomic commit.POST /canvasjoins an already initialized scene; it never creates a competing seed.src/ai-editing/: the agent loop, prompts, tools, and op queue.src/endpoints/: one file per surface —edit.ts,docx.ts,forms.ts,spreadsheet.ts,comment-mark.ts.src/sandbox.ts/scripts/generate-sandbox.ts: the QuickJS sandbox the model's generated code runs in (regenerated byprebuild, not hand-edited).
Scope
- Owns: the AI document-editing session (joining the doc, agent orchestration, applying edits), Canvas/DOCX/forms/spreadsheet AI endpoints, and comment-mark anchoring.
- Not here: the Loro/sync-service wire protocol itself, shared with the web
app via
@macro-inc/collaboration; browser auth and sync HTTP policy stay inapps/web.
Recipes
Add or change a prompt section:
src/ai-editing/prompts/index.tscomposesGROUND_RULES,TEAM,EDITING_RULES,API_COMPLETE, plus one role file per agent — put a rule in the one shared section both roles need, not in both role files.Add a new AI editing endpoint:
src/endpoints/<name>.ts→ register insrc/endpoints/index.ts.Change the sandboxed edit API:
src/ai-editing/doc/orsrc/ai-editing/editor/→scripts/generate-sandbox.ts(regeneratessrc/editor-sandbox-code.ts).Change the Canvas SDK:
src/canvas/editor.tsandschema.ts→scripts/generate-sandbox.ts(regeneratessrc/canvas/sandbox-code.ts). Artifact operations also needisArtifactOpandartifact-prompt.md, the guide given only to users with theenable-canvas-artifactsrollout. Commands validate on a disposable editor and commit once through the live backend.mentionUserinserts the shared person-chip format without flattening other text; ReadCanvas exposes bounded identities/offsets, with one U+FFFC per existing chip in text offsets. It uses the same measured/revalidated commit. Keep asset-reference bookkeeping in its authorized host flow.
Checks
bun run type-check(tsc --noEmit).bunx vitest runfor most unit tests (co-located*.test.ts); spreadsheet has its own configs:bun run test:spreadsheetandbun run test:spreadsheet:integration.just devforwrangler dev --env local. (just dev-localpoints at asrc/server.tsthat no longer exists.)
Gotchas
- This worker never deploys without explicit approval —
just deploy-dev/deploy-prodrungenerate-sandboxfirst; don't run them unprompted.
Related
- Docs:
services/ai-editing-worker/AI_EDITING.md,services/ai-editing-worker/src/spreadsheet/README.md
Canvas browser configuration
Use the existing worker's BROWSER binding in deployed environments, with
CANVAS_RENDER_URL pointing to the web app's app/canvas-render.html bundle.
Locally run an isolated Chromium CDP browser reachable from the worker and set
CANVAS_BROWSER_URL to its HTTP discovery origin plus CANVAS_RENDER_URL to the
preview's HTTPS canvas-render.html. For example pass both through wrangler dev --env local --var CANVAS_BROWSER_URL:<trusted-CDP-origin> --var CANVAS_RENDER_URL:<preview-render-URL>. Keep authentication out of those URLs.
The isolated render context loads no user cookies and never joins live sync.
Without browser configuration, Canvas rendering and measured edits fail clearly;
other document editing endpoints do not require this browser. Do not deploy the
worker or reset an existing preview to configure it.
Local performance scripts in scripts/benchmark-canvas.mjs and
collect-canvas-benchmark-traces.mjs benchmark disposable source copies and export
only safe timing/usage projections. Commands, fixture assumptions, actual results
and cold/warm limitations live in docs/architecture/canvas.md; never print raw
agent session logs or commit a browser storage-state file.