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.

feat(ai-editing): fast mode for inline edits, one model straight to runCode (#6389)

Wolf Mermelstein149ed77a6d00
diff --git a/apps/docs/AI/mcp/tools/edit-document.mdx b/apps/docs/AI/mcp/tools/edit-document.mdx
index a7882e2681..83570f38ef 100644
--- a/apps/docs/AI/mcp/tools/edit-document.mdx
+++ b/apps/docs/AI/mcp/tools/edit-document.mdx
@@ -13,3 +13,4 @@ Apply AI-driven edits to a Macro markdown document in place -- rewriting, insert
| --- | --- | --- | --- |
| `document_id` | string | Yes | The ID of the markdown document to edit. If you are not certain the document is markdown, call ReadMetadata first and check that `fileType` is `md` -- passing an uploaded file here fails. |
| `instructions` | string | Yes | Natural language instructions. For @-mention chips, include each item's ids and details: userId/email for people; documentId/documentName/blockName for documents and similar items; session id for agent sessions; ISO datetime and displayFormat for time chips. For document-card(s), include documentId and documentName per document. You may need to look these up. |
+| `fast` | boolean | No | Set true for one quick, contained edit -- rewrite this paragraph, translate the selected list, fix a heading, bold a phrase. A single model applies it directly in a few seconds. Leave false (the default) for anything with several parts or that restructures the document; the default pipeline plans, dispatches, and reviews its own work, which takes longer but is what multi-step edits need. |
diff --git a/apps/web/src/features/block-md/ai-edit/applyAiOps.ts b/apps/web/src/features/block-md/ai-edit/applyAiOps.ts
index d04f68c435..4f32907574 100644
--- a/apps/web/src/features/block-md/ai-edit/applyAiOps.ts
+++ b/apps/web/src/features/block-md/ai-edit/applyAiOps.ts
@@ -1,13 +1,19 @@
import { Doc } from '@ai-ops/doc';
import type { DocumentOp } from '@ai-ops/editor';
import type { NodeIdMappings } from '@macro-inc/lexical-core/plugins/nodeIdPlugin';
-import type { LexicalEditor } from 'lexical';
+import { $setSelection, type LexicalEditor } from 'lexical';
export function applyAiOps(
editor: LexicalEditor,
mapping: NodeIdMappings,
ops: DocumentOp[]
): void {
+ // The user's selection is usually inside the nodes about to change (they
+ // selected them to ask for the edit). Lexical re-resolves that selection
+ // after every update, and offsets from the old text overrun the new one:
+ // `$getTextNodeOffset: invalid offset 77 for size 61`. Drop it first; the
+ // popup that triggered the edit has already closed.
+ editor.update(() => $setSelection(null), { discrete: true });
const doc = new Doc({ editor, ids: mapping });
for (const op of ops) {
doc.apply(op);
diff --git a/apps/web/src/features/block-md/component/DocumentAiEditBar.tsx b/apps/web/src/features/block-md/component/DocumentAiEditBar.tsx
index f9026019fa..faf1b9d634 100644
--- a/apps/web/src/features/block-md/component/DocumentAiEditBar.tsx
+++ b/apps/web/src/features/block-md/component/DocumentAiEditBar.tsx
@@ -1,11 +1,14 @@
import { mdStore } from '@block-md/signal/markdownBlockData';
import { buildChatEditor } from '@core/component/AI/component/input/buildChatEditor';
import { MarkdownShell } from '@core/component/LexicalMarkdown/builder/MarkdownShell';
-import { toast } from '@core/component/Toast/Toast';
import clickOutside from '@core/directive/clickOutside';
import { TOKENS } from '@core/hotkey/tokens';
import { AnimatedStarIcon } from '@icon/wide-star';
-import { cancelAiEdit, requestAiEdit } from '@service-ai-editing/client';
+import {
+ cancelAiEdit,
+ requestAiEdit,
+ toastAiEditResult,
+} from '@service-ai-editing/client';
import { Button, ComposerSurface, SendButton } from '@ui';
import { createSignal, Show } from 'solid-js';
@@ -44,9 +47,7 @@ export function DocumentAiEditBar(props: { documentId: string }) {
documentId: props.documentId,
prompt: value,
})
- .then((result) => {
- if (result === 'failed') toast.failure('AI edit failed');
- })
+ .then(toastAiEditResult)
.finally(() => setEditing(false));
};
diff --git a/apps/web/src/features/block-md/component/MarkdownPopup.tsx b/apps/web/src/features/block-md/component/MarkdownPopup.tsx
index 156a768ceb..a29bf01c9b 100644
--- a/apps/web/src/features/block-md/component/MarkdownPopup.tsx
+++ b/apps/web/src/features/block-md/component/MarkdownPopup.tsx
@@ -71,6 +71,7 @@ import {
cancelAiEdit,
hasActiveAiEdit,
requestAiEdit,
+ toastAiEditResult,
} from '@service-ai-editing/client';
import { makeResizeObserver } from '@solid-primitives/resize-observer';
import { Button, Toolbar } from '@ui';
@@ -357,15 +358,15 @@ export function MarkdownPopup(props: {
// The highlight is already tracking the selection; flagging the run
// keeps it alive (as the loading indicator) after the popup closes.
setAiEditRunning(true);
+ // Fast mode: one model edits the whole document directly, no supervisor.
// Apply ops locally so the edit lands in this client's undo stack.
requestAiEdit({
documentId: blockId,
prompt: `Request: ${instruction}\nUser is selecting nodes ${nodeIds.join(' ')}. Proceed with requested edit`,
+ mode: 'fast',
onOps: (ops) => applyAiOps(editor, props.lexicalMapping, ops),
})
- .then((result) => {
- if (result === 'failed') toast.failure('AI edit failed');
- })
+ .then(toastAiEditResult)
.finally(() => {
setAiEditLocation(null);
setAiEditRunning(false);
diff --git a/apps/web/src/lib/service-clients/ai-editing-worker/client.ts b/apps/web/src/lib/service-clients/ai-editing-worker/client.ts
index d5e7fe76cc..870ecbc802 100644
--- a/apps/web/src/lib/service-clients/ai-editing-worker/client.ts
+++ b/apps/web/src/lib/service-clients/ai-editing-worker/client.ts
@@ -34,9 +34,34 @@ const MODELS = {
{ provider: 'cerebras', model: 'gpt-oss-120b' },
{ provider: 'anthropic', model: 'claude-haiku-4-5' },
],
+ // The fast path's single model: whole doc in, `runCode` out, no supervisor.
+ // Mirrors the chain the backend EditDocument tool sends for `fast: true`.
+ // Benched on a real inline request (10k-token prompt, one runCode step):
+ // 3.8 Flash 1.5-5 s with no thinking tokens, 3.7 Flash 3.8-5.4 s (~450
+ // thinking tokens even at `low`), 3.5 Flash Lite 0.8-1.1 s with identical
+ // code on three requests. 3.8 leads for headroom on harder edits; Haiku is
+ // the provider-error fallback.
+ fast: [
+ { provider: 'google', model: 'gemini-3.8-flash' },
+ { provider: 'anthropic', model: 'claude-haiku-4-5' },
+ ],
} as const;
-export type AiEditResult = 'ok' | 'failed' | 'cancelled';
+/**
+ * `supervised` runs the full interpreter → supervisor → coders pipeline.
+ * `fast` gives one model the whole document and lets it edit directly; a few
+ * seconds instead of tens, at the cost of the supervisor's review loop. Meant
+ * for small, well-scoped inline edits.
+ */
+export type AiEditMode = 'supervised' | 'fast';
+
+export type AiEditResult =
+ | { kind: 'ok' }
+ | { kind: 'failed' }
+ | { kind: 'cancelled' }
+ /** The worker stopped to ask for something only the user can supply. No
+ * edits were made; `message` says what to add to the request. */
+ | { kind: 'blocked'; message: string };
// In-flight edits by document id. Aborting the fetch cancels the session
// server-side too: the worker threads the request signal into runEditSession
@@ -75,6 +100,8 @@ export function cancelAiEdit(documentId: string): void {
export async function requestAiEdit(args: {
documentId: string;
prompt: string;
+ /** Defaults to the worker's `supervised` pipeline. */
+ mode?: AiEditMode;
onOps?: (ops: DocumentOp[]) => void;
}): Promise<AiEditResult> {
const controller = new AbortController();
@@ -90,6 +117,7 @@ export async function requestAiEdit(args: {
span.setAttr('http.method', 'POST');
span.setAttr('http.url', `${AI_EDITING_WORKER_HOST}/edit`);
span.setAttr('document.id', args.documentId);
+ span.setAttr('edit.mode', args.mode ?? 'supervised');
try {
const token = await getDocumentPermissionToken(args.documentId);
const headers: Record<string, string> = {
@@ -104,6 +132,7 @@ export async function requestAiEdit(args: {
documentId: args.documentId,
prompt: args.prompt,
models: MODELS,
+ mode: args.mode,
interpret: false,
propagate: args.onOps === undefined ? undefined : false,
}),
@@ -119,21 +148,26 @@ export async function requestAiEdit(args: {
message,
stack: new Error(message).stack,
});
- return 'failed';
+ return { kind: 'failed' };
}
- if (args.onOps) {
- const { ops } = (await res.json()) as { ops: DocumentOp[] };
- args.onOps(ops);
+ const { ops, clarification } = (await res.json()) as {
+ ops: DocumentOp[];
+ clarification?: string;
+ };
+ if (clarification !== undefined) {
+ span.setAttr('edit.blocked', true);
+ return { kind: 'blocked', message: clarification };
}
- return 'ok';
+ args.onOps?.(ops);
+ return { kind: 'ok' };
} catch (e) {
if (controller.signal.aborted) {
span.setAttr('http.aborted', true);
- return 'cancelled';
+ return { kind: 'cancelled' };
}
console.error('ai edit request failed', e);
span.error(e);
- return 'failed';
+ return { kind: 'failed' };
} finally {
span.end();
if (editControllers.get(args.documentId) === controller) {
@@ -143,18 +177,20 @@ export async function requestAiEdit(args: {
}
}
+/** Toast for a result that did not apply the edit; a user cancel stays silent. */
+export function toastAiEditResult(result: AiEditResult): void {
+ if (result.kind === 'failed') toast.failure('AI edit failed');
+ if (result.kind === 'blocked') toast.failure(result.message);
+}
+
/**
- * `requestAiEdit` wrapper that toasts `'AI edit failed'` on failure (a user
- * cancel stays silent). The caller supplies a `finally` callback for any
- * post-edit cleanup (e.g. clearing a loading signal).
+ * `requestAiEdit` wrapper that toasts on failure or a request for more detail
+ * (a user cancel stays silent). The caller supplies a `finally` callback for
+ * any post-edit cleanup (e.g. clearing a loading signal).
*/
export function requestAiEditWithToast(
args: { documentId: string; prompt: string },
onSettled: () => void
): void {
- requestAiEdit(args)
- .then((result) => {
- if (result === 'failed') toast.failure('AI edit failed');
- })
- .finally(onSettled);
+ requestAiEdit(args).then(toastAiEditResult).finally(onSettled);
}
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
index a04c3fdce7..ce741cd202 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/schemas.ts
@@ -1515,6 +1515,7 @@ export const DisplayResultsResponse = z.object({ message: z.string() });
export const EditDocument = z.object({
document_id: z.string(),
instructions: z.string(),
+ fast: z.boolean().optional(),
});
export const EditDocumentResponse = z.object({
diff --git a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
index 35127fd2d0..1d076a29d6 100644
--- a/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
+++ b/apps/web/src/lib/service-clients/service-cognition/generated/tools/types.ts
@@ -2533,6 +2533,10 @@ export interface EditDocument {
* Natural language instructions. For @-mention chips, include each item's ids and details: userId/email for people; documentId/documentName/blockName for documents and similar items; session id for agent sessions; ISO datetime and displayFormat for time chips. For document-card(s), include documentId and documentName per document. You may need to look these up.
*/
instructions: string;
+ /**
+ * Set true for one quick, contained edit -- rewrite this paragraph, translate the selected list, fix a heading, bold a phrase. A single model applies it directly in a few seconds. Leave false (the default) for anything with several parts or that restructures the document; the default pipeline plans, dispatches, and reviews its own work, which takes longer but is what multi-step edits need.
+ */
+ fast?: boolean;
}
export interface EditDocumentResponse {
/**
diff --git a/bun.lock b/bun.lock
index f6277ac671..9d8c307d59 100644
--- a/bun.lock
+++ b/bun.lock
@@ -306,6 +306,7 @@
"dependencies": {
"@ai-sdk/anthropic": "^3.0.85",
"@ai-sdk/cerebras": "^2.0.57",
+ "@ai-sdk/google": "^3.0.83",
"@ai-sdk/openai": "^3.0.73",
"@hono/zod-validator": "^0.8.0",
"@loro-mirror/core": "workspace:*",
diff --git a/crates/documents/src/domain/ports/editing.rs b/crates/documents/src/domain/ports/editing.rs
index 5583254165..24d9ca7bd0 100644
--- a/crates/documents/src/domain/ports/editing.rs
+++ b/crates/documents/src/domain/ports/editing.rs
@@ -25,6 +25,17 @@ pub struct EditUsage {
pub output_tokens: u32,
}
+/// Which pipeline the editing worker runs.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum EditMode {
+ /// Interpreter, supervisor, and parallel coders. Reviews its own work
+ /// across rounds; the right choice for multi-part or structural edits.
+ Supervised,
+ /// One model, the whole document, straight to `runCode`. Seconds instead
+ /// of tens of seconds, for a single contained edit.
+ Fast,
+}
+
/// Port for applying AI-driven edits to a document via the editing worker.
#[cfg_attr(test, mockall::automock)]
pub trait EditingWorkerService: Send + Sync + 'static {
@@ -34,6 +45,7 @@ pub trait EditingWorkerService: Send + Sync + 'static {
document_id: &str,
document_token: &DocumentPermissionToken,
instructions: &str,
+ mode: EditMode,
) -> impl Future<Output = anyhow::Result<EditResult>> + Send;
/// Delete all AI edit trace records for `document_id`. Called during
diff --git a/crates/documents/src/inbound/toolset/edit_document.rs b/crates/documents/src/inbound/toolset/edit_document.rs
index af421c9f38..a34b644f3a 100644
--- a/crates/documents/src/inbound/toolset/edit_document.rs
+++ b/crates/documents/src/inbound/toolset/edit_document.rs
@@ -2,7 +2,9 @@
use crate::domain::permission_token::encode_permission_token;
use crate::domain::ports::{
- DocumentService, create::DocumentCreationService, editing::EditingWorkerService,
+ DocumentService,
+ create::DocumentCreationService,
+ editing::{EditMode, EditingWorkerService},
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
@@ -35,6 +37,11 @@ pub struct EditDocument {
description = "Natural language instructions. For @-mention chips, include each item's ids and details: userId/email for people; documentId/documentName/blockName for documents and similar items; session id for agent sessions; ISO datetime and displayFormat for time chips. For document-card(s), include documentId and documentName per document. You may need to look these up."
)]
pub instructions: String,
+ #[serde(default)]
+ #[schemars(
+ description = "Set true for one quick, contained edit -- rewrite this paragraph, translate the selected list, fix a heading, bold a phrase. A single model applies it directly in a few seconds. Leave false (the default) for anything with several parts or that restructures the document; the default pipeline plans, dispatches, and reviews its own work, which takes longer but is what multi-step edits need."
+ )]
+ pub fast: bool,
}
/// The editing worker opens a sync-service session and blocks on the initial
@@ -76,6 +83,16 @@ impl ToolAnnotated for EditDocument {
const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Edit document");
}
+impl EditDocument {
+ fn mode(&self) -> EditMode {
+ if self.fast {
+ EditMode::Fast
+ } else {
+ EditMode::Supervised
+ }
+ }
+}
+
#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for EditDocument
where
@@ -138,7 +155,7 @@ where
internal_error: anyhow::anyhow!("edit cancelled by user. document might be left in a partially edited state."),
});
}
- r = ctx.editing.edit(&self.document_id, &document_token, &self.instructions) => r,
+ r = ctx.editing.edit(&self.document_id, &document_token, &self.instructions, self.mode()) => r,
}
.map_err(|e| ToolCallError {
description: e.to_string(),
diff --git a/crates/documents/src/inbound/toolset/edit_document/test.rs b/crates/documents/src/inbound/toolset/edit_document/test.rs
index 0ae51675f9..7ff8028bb3 100644
--- a/crates/documents/src/inbound/toolset/edit_document/test.rs
+++ b/crates/documents/src/inbound/toolset/edit_document/test.rs
@@ -10,7 +10,7 @@ use crate::domain::models::{
ImportEmailAttachmentRepoArgs, LocationQueryParams, TaskBranchName,
};
use crate::domain::permission_token::decode_permission_token;
-use crate::domain::ports::editing::{EditResult, EditingWorkerService};
+use crate::domain::ports::editing::{EditMode, EditResult, EditingWorkerService};
use crate::domain::response::{
CreateDocumentResponseData, DocumentResponse, GetDocumentResponseData, LocationResponseV3,
};
@@ -394,6 +394,7 @@ impl EntityAccessService for FakeEntityAccessService {
#[derive(Clone, Default)]
struct FakeEditingWorker {
edit_calls: Arc<Mutex<Vec<String>>>,
+ modes: Arc<Mutex<Vec<EditMode>>>,
tokens: Arc<Mutex<Vec<DocumentPermissionToken>>>,
}
@@ -403,11 +404,16 @@ impl EditingWorkerService for FakeEditingWorker {
document_id: &str,
document_token: &DocumentPermissionToken,
_instructions: &str,
+ mode: EditMode,
) -> anyhow::Result<EditResult> {
self.edit_calls
.lock()
.expect("edit calls lock poisoned")
.push(document_id.to_string());
+ self.modes
+ .lock()
+ .expect("edit modes lock poisoned")
+ .push(mode);
self.tokens
.lock()
.expect("edit tokens lock poisoned")
@@ -463,11 +469,20 @@ async fn call_edit_document(
async fn call_edit_document_as(
file_type: &str,
actor: Option<BotId>,
+) -> (ToolResult<EditDocumentResponse>, FakeEditingWorker) {
+ call_edit_document_with(file_type, actor, false).await
+}
+
+async fn call_edit_document_with(
+ file_type: &str,
+ actor: Option<BotId>,
+ fast: bool,
) -> (ToolResult<EditDocumentResponse>, FakeEditingWorker) {
let editing = FakeEditingWorker::default();
let tool = EditDocument {
document_id: TEST_DOCUMENT_ID.to_string(),
instructions: "tidy up the imports".to_string(),
+ fast,
};
let mut context = tool_context(FakeDocumentService::new(file_type), editing.clone());
@@ -522,6 +537,32 @@ async fn rejects_non_markdown_document_without_calling_the_worker() {
/// consulted the content location. Markdown uploaded to S3 is only initialized
/// into sync-service when its upload finalizes, and a location check during
/// that window would reject an edit the sync handshake is designed to serve.
+#[tokio::test]
+async fn fast_flag_selects_the_fast_pipeline() {
+ let (_, editing) = call_edit_document_with("md", None, true).await;
+ assert_eq!(
+ *editing.modes.lock().expect("edit modes lock poisoned"),
+ vec![EditMode::Fast]
+ );
+
+ let (_, editing) = call_edit_document("md").await;
+ assert_eq!(
+ *editing.modes.lock().expect("edit modes lock poisoned"),
+ vec![EditMode::Supervised]
+ );
+}
+
+/// `fast` is optional on the wire so existing callers keep working.
+#[test]
+fn fast_defaults_to_false() {
+ let tool: EditDocument = serde_json::from_value(serde_json::json!({
+ "document_id": TEST_DOCUMENT_ID,
+ "instructions": "x",
+ }))
+ .expect("fast should be optional");
+ assert!(!tool.fast);
+}
+
#[tokio::test]
async fn allows_markdown_document() {
let (result, editing) = call_edit_document("md").await;
diff --git a/crates/documents/src/outbound/editing_worker_client.rs b/crates/documents/src/outbound/editing_worker_client.rs
index 4452c607c6..41de7a6779 100644
--- a/crates/documents/src/outbound/editing_worker_client.rs
+++ b/crates/documents/src/outbound/editing_worker_client.rs
@@ -1,6 +1,6 @@
//! Outbound adapter for the AI editing worker.
-use crate::domain::ports::editing::{EditResult, EditUsage, EditingWorkerService};
+use crate::domain::ports::editing::{EditMode, EditResult, EditUsage, EditingWorkerService};
use macro_sync_service_jwt::DocumentPermissionToken;
use reqwest::Client;
use std::sync::Arc;
@@ -42,11 +42,16 @@ impl EditingWorkerService for ReqwestEditingWorkerClient {
document_id: &str,
document_token: &DocumentPermissionToken,
instructions: &str,
+ mode: EditMode,
) -> anyhow::Result<EditResult> {
let request_body = serde_json::json!({
"documentToken": document_token.as_str(),
"documentId": document_id,
"prompt": instructions,
+ "mode": match mode {
+ EditMode::Supervised => "supervised",
+ EditMode::Fast => "fast",
+ },
"models": {
"supervisor": [
{ "provider": "anthropic", "model": "claude-opus-4-8" },
@@ -72,6 +77,14 @@ impl EditingWorkerService for ReqwestEditingWorkerClient {
{ "provider": "openai", "model": "gpt-5.5" },
{ "provider": "anthropic", "model": "claude-haiku-4-5" },
],
+ // The fast path's single model; mirrors the web client's chain
+ // (apps/web ai-editing-worker/client.ts). Gemini 3.8 Flash ran
+ // a real inline edit in 1.5-5 s with no thinking tokens where
+ // 3.7 Flash took 3.8-5.4 s; Haiku is the provider-error fallback.
+ "fast": [
+ { "provider": "google", "model": "gemini-3.8-flash" },
+ { "provider": "anthropic", "model": "claude-haiku-4-5" },
+ ],
},
"interpret": false,
});
diff --git a/services/ai-editing-worker/AI_EDITING.md b/services/ai-editing-worker/AI_EDITING.md
index 91e1626b46..9b44859968 100644
--- a/services/ai-editing-worker/AI_EDITING.md
+++ b/services/ai-editing-worker/AI_EDITING.md
@@ -68,6 +68,35 @@ A diagram for the animation abstraction flow
propagate → snapshot → mirror → Loro → sync to everyone
```
+### Prompts
+
+System prompts are composed in `ai-editing/prompts/index.ts` from
+single-purpose markdown sections: `GROUND_RULES` (the XML view, ids),
+`TEAM` (the supervisor/writer split), `EDITING_RULES` (how `runCode` and
+`editor` are used), `API_COMPLETE`, and one short role file per agent. A rule
+lives in exactly one section; a role file holds only what is specific to that
+role. Add to a shared section when two roles need something, not to both role
+files.
+
+### Fast mode
+
+`mode: "fast"` on `/edit` skips the interpreter, supervisor, and dispatch
+entirely (`ai-editing/agents/fast.ts`). One model (`models.fast`, a fallback
+chain like the other roles) gets the user's request and the ENTIRE document as
+line-numbered XML, and edits it directly through the same `runCode` /
+`readDocument` / `reportBlocked` tools a coder has. Each `runCode` reply is the
+effect report, so it sees what it changed and can correct itself; the step cap
+is `DEFAULT_MAX_FAST_STEPS`. Everything below `runCode` is unchanged: sandbox,
+ops, animation queue, `Doc.apply`, propagation.
+
+It exists for small, well-scoped inline edits where the supervisor's review
+loop costs more latency than it buys. The web inline selection popup sends
+`mode: "fast"` with `propagate: false`, so the ops come back in the response as
+one dump and are applied client-side into the user's undo stack. The whole-doc
+edit bar stays on the supervised pipeline. The backend `EditDocument` tool
+(chat agents, MCP) exposes it as a `fast` boolean for one quick, contained
+edit; its default remains supervised.
+
### DocumentEditor and ops
`DocumentEditor` is a ergonomic chainable surface the model calls. It has a
diff --git a/services/ai-editing-worker/package.json b/services/ai-editing-worker/package.json
index 6ef0add7a1..7bfc135c76 100644
--- a/services/ai-editing-worker/package.json
+++ b/services/ai-editing-worker/package.json
@@ -13,24 +13,25 @@
"dependencies": {
"@ai-sdk/anthropic": "^3.0.85",
"@ai-sdk/cerebras": "^2.0.57",
+ "@ai-sdk/google": "^3.0.83",
"@ai-sdk/openai": "^3.0.73",
"@hono/zod-validator": "^0.8.0",
"@loro-mirror/core": "workspace:*",
- "@macro-inc/observability": "workspace:*",
"@macro-inc/collaboration": "workspace:*",
"@macro-inc/lexical-core": "workspace:*",
+ "@macro-inc/observability": "workspace:*",
"ai": "^6.0.207",
"ai-fallback": "2",
+ "bitf": "^1.0.2",
"envsafe": "^2.0.3",
+ "flat": "^6.0.1",
"hono": "^4.6.20",
"loro-crdt": "catalog:",
+ "p-queue": "^9.3.0",
"quickjs-emscripten": "^0.31.0",
+ "random-js": "^2.1.0",
"yargs": "^18.0.0",
- "zod": "^4.4.3",
- "bitf": "^1.0.2",
- "flat": "^6.0.1",
- "p-queue": "^9.3.0",
- "random-js": "^2.1.0"
+ "zod": "^4.4.3"
},
"devDependencies": {
"@types/node": "^25.9.3",
diff --git a/services/ai-editing-worker/scripts/edit.ts b/services/ai-editing-worker/scripts/edit.ts
index e5b644445f..1d94dec82c 100644
--- a/services/ai-editing-worker/scripts/edit.ts
+++ b/services/ai-editing-worker/scripts/edit.ts
@@ -1,107 +1,178 @@
#!/usr/bin/env bun
-import yargs from "yargs";
-import { hideBin } from "yargs/helpers";
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
const {
- port,
- "worker-url": workerUrlOpt,
- "ws-url": wsUrl,
- "supervisor-model": supervisorModelFlag,
- "interpret-model": interpretModelFlag,
- "coding-model": codingModelFlag,
- interpret,
- debug,
- out,
- prompt: promptFlag,
- "prompt-file": promptFile,
+ port,
+ 'worker-url': workerUrlOpt,
+ 'ws-url': wsUrl,
+ 'supervisor-model': supervisorModelFlag,
+ 'interpret-model': interpretModelFlag,
+ 'coding-model': codingModelFlag,
+ 'fast-model': fastModelFlag,
+ mode,
+ propagate,
+ interpret,
+ debug,
+ out,
+ prompt: promptFlag,
+ 'prompt-file': promptFile,
} = await yargs(hideBin(process.argv))
- .usage("$0 --prompt <text> --ws-url <url>")
- .help()
- .strict()
- .option("ws-url", { type: "string", demandOption: true, describe: "sync service ws url with token, e.g. wss://…/document/<id>/connect?token=<doc-token>" })
- .option("prompt", { type: "string", describe: "the edit instruction (or use --prompt-file)" })
- .option("port", { type: "number", default: 8933, describe: "worker port" })
- .option("worker-url", { type: "string", describe: "full worker base URL (overrides --port)" })
- .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("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" })
- .check((argv) => {
- if (!argv.prompt && !argv["prompt-file"]) throw new Error("provide --prompt <text> or --prompt-file <path>");
- if (argv._.length > 0) throw new Error(`unexpected positional args: ${argv._.join(" ")} — everything is a flag (use --prompt)`);
- return true;
- })
- .parse();
+ .usage('$0 --prompt <text> --ws-url <url>')
+ .help()
+ .strict()
+ .option('ws-url', {
+ type: 'string',
+ demandOption: true,
+ describe:
+ 'sync service ws url with token, e.g. wss://…/document/<id>/connect?token=<doc-token>',
+ })
+ .option('prompt', {
+ type: 'string',
+ describe: 'the edit instruction (or use --prompt-file)',
+ })
+ .option('port', { type: 'number', default: 8933, describe: 'worker port' })
+ .option('worker-url', {
+ type: 'string',
+ describe: 'full worker base URL (overrides --port)',
+ })
+ .option('supervisor-model', {
+ type: 'string',
+ describe: 'provider:model for the supervisor',
+ })
+ .option('interpret-model', {
+ type: 'string',
+ describe: 'provider:model for the interpret pass',
+ })
+ .option('coding-model', {
+ type: 'string',
+ describe: 'provider:model for the coding agents',
+ })
+ .option('mode', {
+ type: 'string',
+ choices: ['supervised', 'fast'] as const,
+ default: 'supervised',
+ describe:
+ 'supervised = full pipeline; fast = one model edits the whole doc directly (needs --fast-model)',
+ })
+ .option('fast-model', {
+ type: 'string',
+ describe: 'provider:model for --mode fast, e.g. google:gemini-3.7-flash',
+ })
+ .option('propagate', {
+ type: 'boolean',
+ default: true,
+ describe:
+ 'commit edits to the shared doc (use --no-propagate to only compute and return ops, like the inline web path)',
+ })
+ .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',
+ })
+ .check((argv) => {
+ if (!argv.prompt && !argv['prompt-file'])
+ throw new Error('provide --prompt <text> or --prompt-file <path>');
+ if (argv.mode === 'fast' && !argv['fast-model'])
+ throw new Error('--mode fast requires --fast-model');
+ if (argv._.length > 0)
+ throw new Error(
+ `unexpected positional args: ${argv._.join(' ')} — everything is a flag (use --prompt)`
+ );
+ return true;
+ })
+ .parse();
const prompt = promptFile
- ? (await Bun.file(promptFile as string).text()).trim()
- : (promptFlag as string);
+ ? (await Bun.file(promptFile as string).text()).trim()
+ : (promptFlag as string);
const parsed = new URL(wsUrl as string);
-const pathParts = parsed.pathname.split("/");
+const pathParts = parsed.pathname.split('/');
const documentId = pathParts[2];
-const documentToken = parsed.searchParams.get("token");
+const documentToken = parsed.searchParams.get('token');
if (!documentId || !documentToken) {
- console.error("--ws-url must be in the form wss://…/document/<id>/connect?token=<doc-token>");
- process.exit(1);
+ console.error(
+ '--ws-url must be in the form wss://…/document/<id>/connect?token=<doc-token>'
+ );
+ process.exit(1);
}
const parseModel = (flag: string) => {
- const [provider, model] = flag.split(":");
- return { provider: provider!, model: model! };
+ const [provider, model] = flag.split(':');
+ return { provider: provider!, model: model! };
};
const workerUrl = workerUrlOpt ?? `http://localhost:${port}`;
const controller = new AbortController();
-process.on("SIGINT", () => {
- console.error("\naborting request…");
- controller.abort();
+process.on('SIGINT', () => {
+ console.error('\naborting request…');
+ controller.abort();
});
const wantDebug = debug || Boolean(out);
const res = await fetch(`${workerUrl}/edit`, {
- method: "POST",
- signal: controller.signal,
- headers: { "content-type": "application/json" },
- body: JSON.stringify({
- documentToken,
- documentId,
- prompt,
- models: {
- supervisor: [parseModel(supervisorModelFlag)],
- interpret: [parseModel(interpretModelFlag)],
- coding: [parseModel(codingModelFlag)],
- },
- interpret,
- debug: wantDebug,
- }),
- timeout: false,
+ method: 'POST',
+ signal: controller.signal,
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ documentToken,
+ documentId,
+ prompt,
+ models: {
+ supervisor: supervisorModelFlag
+ ? [parseModel(supervisorModelFlag)]
+ : undefined,
+ interpret: interpretModelFlag
+ ? [parseModel(interpretModelFlag)]
+ : undefined,
+ coding: codingModelFlag ? [parseModel(codingModelFlag)] : undefined,
+ fast: fastModelFlag ? [parseModel(fastModelFlag)] : undefined,
+ },
+ mode,
+ propagate,
+ interpret,
+ debug: wantDebug,
+ }),
+ timeout: false,
} as RequestInit & { timeout: boolean }).catch((err) => {
- if (controller.signal.aborted) process.exit(130);
- throw err;
+ if (controller.signal.aborted) process.exit(130);
+ throw err;
});
const body = (await res.json()) as {
- trace?: string;
- replay?: unknown;
+ trace?: string;
+ replay?: unknown;
} & Record<string, unknown>;
if (out && body.replay) {
- await Bun.write(out, JSON.stringify(body.replay));
- const events = (body.replay as { events?: unknown[] }).events ?? [];
- console.log(`wrote replay trace to ${out} (${events.length} events)`);
+ await Bun.write(out, JSON.stringify(body.replay));
+ const events = (body.replay as { events?: unknown[] }).events ?? [];
+ console.log(`wrote replay trace to ${out} (${events.length} events)`);
}
if (wantDebug && body.trace) {
- console.log(body.trace);
- const { trace, replay, ...rest } = body;
- console.log("\n---\n");
- console.log(rest);
+ console.log(body.trace);
+ const { trace, replay, ...rest } = body;
+ console.log('\n---\n');
+ console.log(rest);
} else {
- const { replay, ...rest } = body;
- console.log(rest);
+ const { replay, ...rest } = body;
+ console.log(rest);
}
diff --git a/services/ai-editing-worker/src/ai-editing/agents/coder.ts b/services/ai-editing-worker/src/ai-editing/agents/coder.ts
index 874a0c4991..1e8a242094 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/coder.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/coder.ts
@@ -1,8 +1,6 @@
import { generateText, hasToolCall, type LanguageModel, stepCountIs } from 'ai';
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 { CODER_SYSTEM } from '../prompts';
import {
createImBlockedTool,
createReadDocumentTool,
@@ -14,8 +12,6 @@ import type { RunTaskDeps } from './types';
export type { RunTaskDeps } from './types';
-export const CHILD_SYSTEM = `${SHARED}\n${CODER}\n${API_COMPLETE}`;
-
/**
* Default per-coder step cap.
*
@@ -42,7 +38,7 @@ export async function coder(
stepCountIs(deps.maxSteps ?? DEFAULT_MAX_CODER_STEPS),
hasToolCall('reportBlocked'),
],
- system: CHILD_SYSTEM,
+ system: CODER_SYSTEM,
// System, tools, and task/context are fixed for this coder's whole run;
// one cache breakpoint on the opening message covers all of them.
messages: cachedPrompt(buildPrompt(task, deps.context, deps.request)),
diff --git a/services/ai-editing-worker/src/ai-editing/agents/fast.test.ts b/services/ai-editing-worker/src/ai-editing/agents/fast.test.ts
new file mode 100644
index 0000000000..2accaba401
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/agents/fast.test.ts
@@ -0,0 +1,248 @@
+import type {
+ LanguageModelV3CallOptions,
+ LanguageModelV3Usage,
+} from '@ai-sdk/provider';
+import { MockLanguageModelV3 } from 'ai/test';
+import { describe, expect, it } from 'vitest';
+import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
+import { mockAwarenessSource } from '../awareness/awareness-source';
+import { Doc } from '../doc/doc';
+import type { DocumentOp } from '../editor';
+import type { CoderRunCode, DispatchEditTrace } from '../tools';
+import { serializeWithXml } from '../utils';
+import { fastEditor } from './fast';
+
+const usage: LanguageModelV3Usage = {
+ inputTokens: {
+ total: 10,
+ noCache: undefined,
+ cacheRead: undefined,
+ cacheWrite: undefined,
+ },
+ outputTokens: { total: 5, text: 5, reasoning: undefined },
+};
+
+const finish = { unified: 'stop' as const, raw: undefined };
+
+/** The fast path declares snippets as pairs (see SnippetShape). */
+function runCodeCall(id: string, input: CoderRunCode) {
+ const snippets = Object.entries(input.snippets ?? {}).map(([key, text]) => ({
+ key,
+ text,
+ }));
+ return {
+ type: 'tool-call' as const,
+ toolCallId: id,
+ toolName: 'runCode',
+ input: JSON.stringify({ code: input.code, snippets }),
+ };
+}
+
+/** A runner that plays back canned ops, as if the sandbox produced them. */
+const replay = (opsByCall: DocumentOp[][]) => (): DocumentOp[] =>
+ opsByCall.shift() ?? [];
+
+describe('fastEditor', () => {
+ it('edits in one runCode call, stops on the clean effect report, and records the code', async () => {
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ const paragraphId = serializeWithXml(session).match(/<p id="([^"]+)"/)![1]!;
+
+ const calls: LanguageModelV3CallOptions[] = [];
+ let step = 0;
+ const model = new MockLanguageModelV3({
+ modelId: 'fast-mock',
+ doGenerate: async (options) => {
+ calls.push(options);
+ return step++ === 0
+ ? {
+ content: [
+ runCodeCall('call-1', {
+ code: `editor.setText('${paragraphId}', snippets.text)`,
+ snippets: { text: 'goodbye world' },
+ }),
+ ],
+ finishReason: { unified: 'tool-calls' as const, raw: undefined },
+ usage,
+ warnings: [],
+ }
+ : {
+ content: [{ type: 'text' as const, text: 'Replaced the text.' }],
+ finishReason: finish,
+ usage,
+ warnings: [],
+ };
+ },
+ });
+
+ const codes: CoderRunCode[][] = [];
+ const traces: DispatchEditTrace[] = [];
+ const ops: DocumentOp[] = [];
+ const result = await fastEditor(session, 'say goodbye', model, {
+ borrowWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ runner: replay([
+ [{ kind: 'setText', node: paragraphId, text: 'goodbye world' }],
+ ]),
+ typingAnimations: false,
+ sleep: async () => {},
+ onOps: (batch) => ops.push(...batch),
+ onCoderResult: (batch) => codes.push(batch),
+ onEditTrace: (trace) => traces.push(trace),
+ });
+
+ // The whole document went in the opening prompt.
+ const firstPrompt = calls[0]!.prompt;
+ const openingUser = JSON.stringify(firstPrompt);
+ expect(openingUser).toContain(paragraphId);
+ expect(openingUser).toContain('Request: say goodbye');
+ // The first step must be a tool call.
+ expect(calls[0]!.toolChoice).toEqual({ type: 'required' });
+
+ expect(serializeWithXml(session)).toContain('goodbye world');
+ expect(ops).toHaveLength(1);
+ // A clean CHANGED report ends the run; no summary round trip.
+ expect(calls).toHaveLength(1);
+ expect(result.steps).toHaveLength(1);
+ expect(result.text).toBe('Applied edits.');
+ expect(result.clarification).toBeUndefined();
+
+ expect(codes).toEqual([
+ [
+ {
+ code: `editor.setText('${paragraphId}', snippets.text)`,
+ snippets: { text: 'goodbye world' },
+ result: expect.stringContaining('CHANGED'),
+ },
+ ],
+ ]);
+ expect(traces).toHaveLength(1);
+ expect(traces[0]!.runCodeAt).toHaveLength(1);
+ expect(traces[0]!.coderFinishedAt).toBeGreaterThan(0);
+ });
+
+ it('retries after an error reply instead of stopping', async () => {
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ const paragraphId = serializeWithXml(session).match(/<p id="([^"]+)"/)![1]!;
+ const code = `editor.setText('${paragraphId}', snippets.text)`;
+ let step = 0;
+ const model = new MockLanguageModelV3({
+ modelId: 'fast-mock',
+ doGenerate: async () =>
+ step++ === 0
+ ? {
+ // Missing snippet: the runtime rejects it before the sandbox.
+ content: [runCodeCall('call-1', { code, snippets: {} })],
+ finishReason: { unified: 'tool-calls' as const, raw: undefined },
+ usage,
+ warnings: [],
+ }
+ : {
+ content: [
+ runCodeCall('call-2', { code, snippets: { text: 'fixed' } }),
+ ],
+ finishReason: { unified: 'tool-calls' as const, raw: undefined },
+ usage,
+ warnings: [],
+ },
+ });
+
+ const codes: CoderRunCode[][] = [];
+ const result = await fastEditor(session, 'fix it', model, {
+ borrowWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ // The first call fails validation before the runner; only the retry runs.
+ runner: replay([[{ kind: 'setText', node: paragraphId, text: 'fixed' }]]),
+ typingAnimations: false,
+ sleep: async () => {},
+ onCoderResult: (batch) => codes.push(batch),
+ });
+
+ expect(result.steps).toHaveLength(2);
+ expect(codes[0]).toHaveLength(2);
+ expect(codes[0]![0]!.result).toMatch(/^error:/);
+ expect(codes[0]![0]!.snippets).toEqual({});
+ expect(codes[0]![1]!.snippets).toEqual({ text: 'fixed' });
+ expect(serializeWithXml(session)).toContain('fixed');
+ });
+
+ it('fails loudly when the step cap is hit without a successful edit', async () => {
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ // Every call references a snippet it never supplies, so every reply is an
+ // error and no step ever reports CHANGED.
+ const model = new MockLanguageModelV3({
+ modelId: 'fast-mock',
+ doGenerate: async () => ({
+ content: [
+ runCodeCall('call', {
+ code: "editor.setText('nope', snippets.text)",
+ snippets: {},
+ }),
+ ],
+ finishReason: { unified: 'tool-calls' as const, raw: undefined },
+ usage,
+ warnings: [],
+ }),
+ });
+
+ await expect(
+ fastEditor(session, 'fix it', model, {
+ borrowWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ runner: () => [],
+ maxSteps: 2,
+ sleep: async () => {},
+ })
+ ).rejects.toThrow(/made no change in 2 step\(s\)/);
+ });
+
+ it('surfaces reportBlocked as a clarification and stops', async () => {
+ const session = createEditingSession();
+ loadMarkdown(session, 'hello world');
+ let generateCount = 0;
+ const model = new MockLanguageModelV3({
+ modelId: 'fast-mock',
+ doGenerate: async () => {
+ generateCount++;
+ return {
+ content: [
+ {
+ type: 'tool-call' as const,
+ toolCallId: 'call-1',
+ toolName: 'reportBlocked',
+ input: JSON.stringify({ message: 'Which paragraph?' }),
+ },
+ ],
+ finishReason: { unified: 'tool-calls' as const, raw: undefined },
+ usage,
+ warnings: [],
+ };
+ },
+ });
+
+ const result = await fastEditor(session, 'fix it', model, {
+ borrowWriter: async () => ({
+ doc: new Doc(session),
+ awarenessSource: mockAwarenessSource(),
+ release: () => {},
+ }),
+ runner: () => [],
+ sleep: async () => {},
+ });
+
+ expect(generateCount).toBe(1);
+ expect(result.clarification).toBe('Which paragraph?');
+ expect(serializeWithXml(session)).toContain('hello world');
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/agents/fast.ts b/services/ai-editing-worker/src/ai-editing/agents/fast.ts
new file mode 100644
index 0000000000..b038594f16
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/agents/fast.ts
@@ -0,0 +1,207 @@
+import { Telemetry } from '@macro-inc/observability';
+import { generateText, hasToolCall, type LanguageModel, stepCountIs } from 'ai';
+import type { LexicalSession } from '../ai-toolkit';
+import type { DocumentOp } from '../editor';
+import { FAST_SYSTEM } from '../prompts';
+import type { DocumentOpQueueParams } from '../queue';
+import type { CodeRunner } from '../runtime';
+import { TokenTracker } from '../token-tracker';
+import {
+ type CoderRunCode,
+ createImBlockedTool,
+ createReadDocumentTool,
+ createRunCodeTool,
+ type DispatchEditTrace,
+ type SnippetPair,
+ snippetsToRecord,
+ type Writer,
+} from '../tools';
+import { numberLines, serializeWithXml } from '../utils';
+import { cachedPrompt, EDIT_PROVIDER_OPTIONS } from './model-options';
+
+/**
+ * Step cap for the fast editor: one `runCode` that does the whole request,
+ * plus room to read the effect report and correct it. The whole point of the
+ * mode is a single model on the hot path, so this stays well under the
+ * supervised pipeline's 7-turn × 7-step envelope.
+ */
+export const DEFAULT_MAX_FAST_STEPS = 4;
+
+export type FastEditorOptions = {
+ borrowWriter: () => Promise<Writer>;
+ runner: CodeRunner;
+ maxSteps?: number;
+ params?: DocumentOpQueueParams;
+ typingAnimations?: boolean;
+ sleep?: (ms: number) => Promise<void>;
+ signal?: AbortSignal;
+ onOps?: (ops: DocumentOp[]) => void;
+ onCoderResult?: (codes: CoderRunCode[]) => void;
+ onEditTrace?: (edit: DispatchEditTrace) => void;
+};
+
+/**
+ * Stop once a step's `runCode` calls all came back `ok` with a `CHANGED`
+ * report. The model would otherwise spend a full round trip — measured at
+ * 4.3 s on a 10k-token context — writing a one-line summary nobody reads.
+ * Errors and `NO CHANGE` replies don't match, so the model still gets its
+ * retry; a wrong-but-successful edit is the trade for that round trip.
+ */
+type StepLike = {
+ toolResults: ReadonlyArray<{ toolName: string; output: unknown }>;
+};
+
+/** Every `runCode` in this step came back `ok` with a `CHANGED` report. */
+export function stepHasCleanEdit(step: StepLike): boolean {
+ const results = step.toolResults.filter((r) => r.toolName === 'runCode');
+ return (
+ results.length > 0 &&
+ results.every(
+ (r) =>
+ typeof r.output === 'string' &&
+ r.output.startsWith('ok') &&
+ r.output.includes('CHANGED')
+ )
+ );
+}
+
+export const hasCleanEdit = ({
+ steps,
+}: {
+ steps: ReadonlyArray<StepLike>;
+}): boolean => {
+ const last = steps.at(-1);
+ return last !== undefined && stepHasCleanEdit(last);
+};
+
+export function buildFastPrompt(request: string, document: string): string {
+ return `Request: ${request}\n\n<document>\n${document}\n</document>`;
+}
+
+/**
+ * The hot path: no interpreter, no supervisor, no dispatch. One model gets the
+ * user's request and the whole document and edits it directly through
+ * `runCode`, seeing each call's effect report so it can correct itself.
+ * Everything below `runCode` (sandbox, ops, animation queue, `Doc.apply`,
+ * propagation) is the same machinery the supervised pipeline uses.
+ */
+export async function fastEditor(
+ session: LexicalSession,
+ request: string,
+ model: LanguageModel,
+ opts: FastEditorOptions
+) {
+ const tracker = new TokenTracker();
+ const span = Telemetry.span('edit.fast');
+ const trace: DispatchEditTrace = {
+ coderStartedAt: Date.now(),
+ coderFinishedAt: 0,
+ runCodeAt: [],
+ runCodeResults: [],
+ };
+ const stepDurationsMs: number[] = [];
+ let lastStepAt = Date.now();
+
+ const writer = await opts.borrowWriter();
+ try {
+ const document = numberLines(serializeWithXml(session));
+ span.setAttr('document.chars', document.length);
+ span.setAttr(
+ 'gen_ai.request.model',
+ (model as { modelId: string }).modelId
+ );
+
+ const result = await generateText({
+ model,
+ stopWhen: [
+ stepCountIs(opts.maxSteps ?? DEFAULT_MAX_FAST_STEPS),
+ hasToolCall('reportBlocked'),
+ hasCleanEdit,
+ ],
+ system: FAST_SYSTEM,
+ messages: cachedPrompt(buildFastPrompt(request, document)),
+ tools: {
+ runCode: createRunCodeTool({
+ session,
+ doc: writer.doc,
+ awarenessSource: writer.awarenessSource,
+ params: opts.params,
+ typingAnimations: opts.typingAnimations,
+ sleep: opts.sleep,
+ runner: opts.runner,
+ onOps: opts.onOps,
+ onRunCode: () => trace.runCodeAt.push(Date.now()),
+ onRunCodeResult: (reply) => trace.runCodeResults.push(reply),
+ span,
+ }),
+ readDocument: createReadDocumentTool({ session }),
+ reportBlocked: createImBlockedTool(
+ 'Call this when the request cannot be carried out, or needs information only the user can supply.',
+ true
+ ),
+ },
+ providerOptions: EDIT_PROVIDER_OPTIONS,
+ abortSignal: opts.signal,
+ // The first thing out of the model must be an edit, not a plan.
+ prepareStep: ({ stepNumber }) =>
+ stepNumber === 0 ? { toolChoice: 'required' as const } : {},
+ onStepFinish: () => {
+ const now = Date.now();
+ stepDurationsMs.push(now - lastStepAt);
+ lastStepAt = now;
+ },
+ });
+
+ tracker.add(model as { modelId: string }, result.totalUsage);
+ // A call the schema rejected never executed and has no result to pair
+ // with; its raw input is whatever the model sent, not our shape.
+ const toolCalls = result.steps
+ .flatMap((step) => step.toolCalls)
+ .filter((call) => !call.invalid);
+ const blocked = toolCalls.find((call) => call.toolName === 'reportBlocked');
+ const clarification = (blocked?.input as { message: string } | undefined)
+ ?.message;
+
+ const codes: CoderRunCode[] = toolCalls
+ .filter((call) => call.toolName === 'runCode')
+ .map((call, i) => {
+ const input = call.input as { code: string; snippets?: SnippetPair[] };
+ return {
+ code: input.code,
+ snippets: snippetsToRecord(input.snippets),
+ result: trace.runCodeResults[i],
+ };
+ });
+ opts.onCoderResult?.(codes);
+ trace.coderFinishedAt = Date.now();
+ opts.onEditTrace?.(trace);
+
+ span.setAttr('steps.count', result.steps.length);
+ span.setAttr('run_code.count', codes.length);
+ span.setAttr('edit.blocked', blocked !== undefined);
+
+ // Hitting the step cap with nothing but errors or NO CHANGE replies is a
+ // failed edit, not a quiet success; say so rather than returning no ops.
+ if (blocked === undefined && !result.steps.some(stepHasCleanEdit)) {
+ throw new Error(
+ `fast edit made no change in ${result.steps.length} step(s): ${
+ trace.runCodeResults.at(-1)?.split('\n')[0] ?? 'no runCode call'
+ }`
+ );
+ }
+
+ return {
+ text: result.text || 'Applied edits.',
+ totalUsage: tracker,
+ steps: result.steps,
+ stepDurationsMs,
+ clarification,
+ };
+ } catch (e) {
+ span.error(e);
+ throw e;
+ } finally {
+ writer.release();
+ span.end();
+ }
+}
diff --git a/services/ai-editing-worker/src/ai-editing/agents/index.ts b/services/ai-editing-worker/src/ai-editing/agents/index.ts
index 766898cef5..ef92a798d5 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/index.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/index.ts
@@ -1,4 +1,9 @@
-export { CHILD_SYSTEM, coder } from './coder';
+export { coder } from './coder';
+export {
+ DEFAULT_MAX_FAST_STEPS,
+ type FastEditorOptions,
+ fastEditor,
+} from './fast';
export { interpreter } from './interpreter';
export { supervisor } from './supervisor';
export type { RunAgentOptions, RunTaskDeps } from './types';
diff --git a/services/ai-editing-worker/src/ai-editing/agents/model-options.ts b/services/ai-editing-worker/src/ai-editing/agents/model-options.ts
index 89095d4a62..a8e5cdb703 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/model-options.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/model-options.ts
@@ -1,10 +1,16 @@
import type { AnthropicProviderOptions } from '@ai-sdk/anthropic';
+import type { GoogleGenerativeAIProviderOptions } from '@ai-sdk/google';
import type { ModelMessage } from 'ai';
export const EDIT_PROVIDER_OPTIONS = {
anthropic: {
thinking: { type: 'disabled' },
} satisfies AnthropicProviderOptions,
+ // Gemini 3.x defaults to medium thinking; the fast path wants tokens out,
+ // not deliberation. `runCode` takes arbitrary JS, so there is little to plan.
+ google: {
+ thinkingConfig: { thinkingLevel: 'low' },
+ } satisfies GoogleGenerativeAIProviderOptions,
};
/**
diff --git a/services/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts b/services/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts
index 89a33178df..1a9790d0b2 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/supervisor.test.ts
@@ -4,7 +4,7 @@ import type {
} from '@ai-sdk/provider';
import { MockLanguageModelV3 } from 'ai/test';
import { describe, expect, it } from 'vitest';
-import type { ResolvedModels } from '../../run-edit';
+import type { SupervisedModels } from '../../run-edit';
import { createEditingSession, loadMarkdown } from '../ai-toolkit/session';
import { mockAwarenessSource } from '../awareness/awareness-source';
import { Doc } from '../doc/doc';
@@ -137,7 +137,7 @@ describe('supervisor — streamed dispatch', () => {
supervisor: supervisorModel,
interpret: codingModel,
coding: () => codingModel,
- } as unknown as ResolvedModels;
+ } as unknown as SupervisedModels;
const session = createEditingSession();
loadMarkdown(session, 'hello world');
diff --git a/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts b/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts
index 6e37184f84..dc505dee4f 100644
--- a/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts
+++ b/services/ai-editing-worker/src/ai-editing/agents/supervisor.ts
@@ -1,11 +1,8 @@
import { type Span, Telemetry } from '@macro-inc/observability';
import { hasToolCall, stepCountIs, streamText } from 'ai';
-import type { ResolvedModels } from '../../run-edit';
+import type { SupervisedModels } from '../../run-edit';
import type { LexicalSession } from '../ai-toolkit';
-import API_COMPACT from '../prompts/API_COMPACT.md';
-import INTERPRET from '../prompts/INTERPRET.md';
-import SHARED from '../prompts/SHARED.md';
-import SUPERVISOR from '../prompts/SUPERVISOR.md';
+import { INTERPRET_SYSTEM, SUPERVISOR_SYSTEM } from '../prompts';
import { TokenTracker } from '../token-tracker';
import { createDispatchTool, createImBlockedTool } from '../tools';
import { numberLines, serializeWithXml } from '../utils';
@@ -17,16 +14,10 @@ import type { RunAgentOptions } from './types';
export type { RunAgentOptions } from './types';
-// TODO(wolf): figure out if we want this. Leaving it off for now.
-const USE_COMPACT = false;
-
-const MASTER_SYSTEM = `${SHARED}\n${SUPERVISOR}${USE_COMPACT ? `\n${API_COMPACT}` : ''}`;
-const INTERPRET_SYSTEM = `${SHARED}\n${INTERPRET}`;
-
export async function supervisor(
session: LexicalSession,
request: string,
- models: ResolvedModels,
+ models: SupervisedModels,
opts: RunAgentOptions
) {
const serialize = (sess: LexicalSession) =>
@@ -117,7 +108,7 @@ export async function supervisor(
const result = streamText({
model: models.supervisor,
stopWhen: [stepCountIs(7), hasToolCall('reportBlocked')],
- system: MASTER_SYSTEM,
+ system: SUPERVISOR_SYSTEM,
messages: cachedPrompt(prompt),
tools,
providerOptions: EDIT_PROVIDER_OPTIONS,
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/CODER.md b/services/ai-editing-worker/src/ai-editing/prompts/CODER.md
index c22a6fbe50..a2e1c09b1f 100644
--- a/services/ai-editing-worker/src/ai-editing/prompts/CODER.md
+++ b/services/ai-editing-worker/src/ai-editing/prompts/CODER.md
@@ -7,42 +7,3 @@ You carry out one task from a supervisor by writing plain JavaScript against a s
The task may be a single small change or a larger set of related changes confined to one region of the document -- either way, you MUST carry out the **whole** instruction before you summarize. Drive as many `editor` calls as the task needs (a loop, or several calls in one `runCode`); you don't have to stop after one change.
You do not see the whole document by default -- only a line-numbered XML window around the ids mentioned in the supervisor's instruction. Everything you need is usually in that window. If you need an id or region that isn't shown, call `readDocument` to get the ENTIRE document as line-numbered XML, then proceed -- do this before ever reporting yourself blocked.
-
-## How you write edits
-
-You call `runCode(code, snippets?)` with plain JS statements. The only things in scope are `editor` and `snippets`. No `$`-helpers, no imports, no `s`, no `$getRoot`. For example:
-
-```js
-editor.convertToHeading('b14', 2);
-editor.bold('b5', 'Bluejay');
-```
-
-- Each method produces an edit(s); the system then animates and applies them.
-- **Address nodes by their `id`** from the XML. Block edits take a block id; a few
- inline methods (`boldNode`, `formatNode`, …) take a `<t id>` text-node id.
-- **Creators return a handle** to the new node you can use in later calls:
- ```js
- const p = editor.insertParagraphAfter('b14', 'Intro');
- editor.bold(p, 'Intro');
- ```
-- **Offsets (`at`) are character positions in the block's plain text** — `0` is the start, `text.length` is the end. Inline objects (line breaks, equations, dates) do NOT count as characters. **Never guess an offset.** You MUST compute it from the actual text: `snippets.line1.length` for the end of a line, `text.indexOf('word')` for a position inside it. Guessing small integers like `1, 2, 3` will split words apart.
-- **Multi-line content → separate paragraphs, not line breaks:** if you need to write multiple lines of content, you should insert separate paragraph nodes. `insertLineBreak` produces a *soft* break (Shift+Enter) within a single block - only use it when the content is semantically one unit split across visual lines (poetry, addresses, signature blocks). For ordinary multi-line content:
- ```js
- editor.setText(id, snippets.line1);
- const p2 = editor.insertParagraphAfter(id, snippets.line2);
- editor.insertParagraphAfter(p2, snippets.line3);
- ```
- When you do need `insertLineBreak`, the `at` offset counts only characters (inline objects don't count). Append each line with `insertTextAfterInline(brRef, text)` and accumulate the running text length manually.
-- Pass **plain text only** -- you MUST NOT ever use XML/markdown syntax. `editor.setText(id, '# x')` inserts the literal characters `# x`, it does not make a heading. We do not support or understand Markdown or XML in our editor.
-- **`setText(id, text)` fully replaces a node's content and clears all inline formatting** -- use it whenever you want to overwrite a text node entirely with plain text. `replace(id, find, to)` is only for partial substitutions where `find` is a known substring and you want to preserve surrounding formatting. **For a code block, always rewrite its whole body with `setText` -- never use `replace` on a code block.**
-- **All text content goes in the `snippets` argument of your runCode call** -- `runCode({ code: "editor.setText('b3', snippets.intro)", snippets: { intro: "Your composed text." } })` -- referenced as `snippets.KEY` in the code. NEVER embed prose as a string literal inside `code`, so that quotes and apostrophes don't break the code. Use snippets. **Snippet values are raw plain text, so do not escape anything inside them.** Write a literal `"` for a quote, never `\"`; a literal `'` for an apostrophe, never `\'`. Backslash-escaping a snippet value inserts a literal backslash into the document.
-- If a call references an id that doesn't exist, you get an error back naming it -- re-read the regions shown, pick the right id, and try again. Don't repeat a failing call.
-- Do the whole task in ONE `runCode` call. The snippet is arbitrary JavaScript, so any number of `editor.*` calls belong in the same call — splitting them across calls costs a round trip and buys nothing. Additional calls are for recovering from an error.
-- Every `runCode` reply states the observed effect: `CHANGED -- modified/added/removed <ids>`, or `NO CHANGE` if the document is byte-identical afterwards. Check the ids are the ones you meant.
-- If the instruction refers to a node you **cannot see** in your window, do NOT guess or invent an id. First call `readDocument` to view the whole document and locate the real id. Only if it is genuinely absent should you call `reportBlocked({ message })` to hand the problem back to the supervisor -- that ends your task, so don't also call `runCode`.
-- You may use ordinary JS (loops, arrays) to drive many calls. You have the full power of plain JavaScript at your disposal.
-- It is **not** your job to try to reason about *why* we are editing the document.
-- We prefer replacements of text over entire node swaps
-- Don't riff off the instruction, do what you are told
-
-Apply the whole instruction, then reply with a one-line summary (no tool call).
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/EDITING_RULES.md b/services/ai-editing-worker/src/ai-editing/prompts/EDITING_RULES.md
new file mode 100644
index 0000000000..540990f1f1
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/prompts/EDITING_RULES.md
@@ -0,0 +1,39 @@
+## How you write edits
+
+You call `runCode(code, snippets?)` with plain JS statements. The only things in scope are `editor` and `snippets`. No `$`-helpers, no imports, no `s`, no `$getRoot`. For example:
+
+```js
+editor.convertToHeading('b14', 2);
+editor.bold('b5', 'Bluejay');
+```
+
+- Each method produces an edit(s); the system then animates and applies them.
+- **Address nodes by their `id`** from the XML. Block edits take a block id; a few
+ inline methods (`boldNode`, `formatNode`, …) take a `<t id>` text-node id.
+- **Creators return a handle** to the new node you can use in later calls:
+ ```js
+ const p = editor.insertParagraphAfter('b14', 'Intro');
+ editor.bold(p, 'Intro');
+ ```
+- **Offsets (`at`) are character positions in the block's plain text** — `0` is the start, `text.length` is the end. Inline objects (line breaks, equations, dates) do NOT count as characters. **Never guess an offset.** You MUST compute it from the actual text: `snippets.line1.length` for the end of a line, `text.indexOf('word')` for a position inside it. Guessing small integers like `1, 2, 3` will split words apart.
+- **Multi-line content → separate paragraphs, not line breaks:** if you need to write multiple lines of content, you should insert separate paragraph nodes. `insertLineBreak` produces a *soft* break (Shift+Enter) within a single block - only use it when the content is semantically one unit split across visual lines (poetry, addresses, signature blocks). For ordinary multi-line content:
+ ```js
+ editor.setText(id, snippets.line1);
+ const p2 = editor.insertParagraphAfter(id, snippets.line2);
+ editor.insertParagraphAfter(p2, snippets.line3);
+ ```
+ When you do need `insertLineBreak`, the `at` offset counts only characters (inline objects don't count). Append each line with `insertTextAfterInline(brRef, text)` and accumulate the running text length manually.
+- Pass **plain text only** -- you MUST NOT ever use XML/markdown syntax. `editor.setText(id, '# x')` inserts the literal characters `# x`, it does not make a heading. We do not support or understand Markdown or XML in our editor.
+- **`setText(id, text)` fully replaces a node's content and clears all inline formatting** -- use it whenever you want to overwrite a text node entirely with plain text. `replace(id, find, to)` is only for partial substitutions where `find` is a known substring and you want to preserve surrounding formatting. **For a code block, always rewrite its whole body with `setText` -- never use `replace` on a code block.**
+- **All text content goes in the `snippets` argument of your runCode call** -- `runCode({ code: "editor.setText('b3', snippets.intro)", snippets: [{ key: "intro", text: "Your composed text." }] })` -- a list of `{ key, text }` pairs, each referenced as `snippets.KEY` in the code. Every key your code uses MUST appear in the list. NEVER embed prose as a string literal inside `code`, so that quotes and apostrophes don't break the code. Use snippets. **Snippet values are raw plain text, so do not escape anything inside them.** Write a literal `"` for a quote, never `\"`; a literal `'` for an apostrophe, never `\'`. Backslash-escaping a snippet value inserts a literal backslash into the document.
+- If a call references an id that doesn't exist, you get an error back naming it -- re-read the regions shown, pick the right id, and try again. Don't repeat a failing call.
+- Do the whole task in ONE `runCode` call. The snippet is arbitrary JavaScript, so any number of `editor.*` calls belong in the same call — splitting them across calls costs a round trip and buys nothing. Additional calls are for recovering from an error.
+- Every `runCode` reply states the observed effect: `CHANGED -- modified/added/removed <ids>`, or `NO CHANGE` if the document is byte-identical afterwards. Check the ids are the ones you meant.
+- If the instruction refers to a node you **cannot see** in your window, do NOT guess or invent an id. First call `readDocument` to view the whole document and locate the real id. Only if it is genuinely absent should you call `reportBlocked({ message })` to hand the problem back -- that ends your task, so don't also call `runCode`.
+- You may use ordinary JS (loops, arrays) to drive many calls. You have the full power of plain JavaScript at your disposal.
+- It is **not** your job to try to reason about *why* we are editing the document.
+- We prefer replacements of text over entire node swaps
+- Use native editor objects when appropriate, like dividers, tables, etc. Do not simulate native objects with plain text, like `======` for a divider.
+- Don't riff off the instruction, do what you are told
+
+Apply the whole instruction, then reply with a one-line summary (no tool call).
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/FAST.md b/services/ai-editing-worker/src/ai-editing/prompts/FAST.md
new file mode 100644
index 0000000000..b2b5eb7db0
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/prompts/FAST.md
@@ -0,0 +1,7 @@
+# Role: Editor (fast mode)
+
+You are the sole editor. There is no supervisor and no other writers: the user's request IS your task, and you carry it out end to end by writing plain JavaScript against `editor`, then replying with a one-line summary.
+
+- You see the ENTIRE document, line-numbered. When the request names node ids (e.g. "User is selecting nodes ..."), that is the region the user means; stay within it unless the request clearly asks for more.
+- **Do not write any text before your first tool call.** Your first output must be a `runCode` call that carries out the whole request. Check each reply's effect report and fix anything that is not what you meant; call `readDocument` to see the document after your own edits.
+- Call `reportBlocked` only when the request cannot be carried out or needs information only the user can give (e.g. an id for a mention or document card that was not provided). Your message must tell the user what to supply. Never use it because the edit is large.
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/GROUND_RULES.md b/services/ai-editing-worker/src/ai-editing/prompts/GROUND_RULES.md
new file mode 100644
index 0000000000..d98882b708
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/prompts/GROUND_RULES.md
@@ -0,0 +1,7 @@
+Ground rules:
+
+- The document is shown to you as **a read-only structural XML *view*** -- the user sees the actual rendered rich text in their editor. The XML is never written back..
+- The XML shows the document's tree: block nodes (`<p>`, `<h1>`–`<h6>`, `<blockquote>`, `<custom-code>`, `<ul>`, `<li>`, `<table>`, etc.) each with an `id` attribute; inline text runs as `<t id="...">` with format attributes (`bold="true"`, `italic="true"`, `underline="true"`, `strikethrough="true"`, `code="true"`).
+- Address any node by its `id` attribute from the XML.
+
+Your role-specific instructions follow.
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/SHARED.md b/services/ai-editing-worker/src/ai-editing/prompts/SHARED.md
deleted file mode 100644
index eb4bbbe8bd..0000000000
--- a/services/ai-editing-worker/src/ai-editing/prompts/SHARED.md
+++ /dev/null
@@ -1,15 +0,0 @@
-# How this system works
-
-You are one role in a two-role editing system for handling user requests to edit a document:
-
-- **Supervisor** -- turns the user's request into small, mechanical edit instructions and dispatches them to writers in rounds, reviewing the resulting diff after each round until the request is done.
-- **Writer** -- receives ONE mechanical edit instruction and carries it out by running mechanical document edits.
-
-Shared ground rules for both roles:
-
-- The document is shown to you as **a read-only structural XML *view*** -- the user sees the actual rendered rich text in their editor. The XML is never written back..
-- The XML shows the document's tree: block nodes (`<p>`, `<h1>`–`<h6>`, `<blockquote>`, `<custom-code>`, `<ul>`, `<li>`, `<table>`, etc.) each with an `id` attribute; inline text runs as `<t id="...">` with format attributes (`bold="true"`, `italic="true"`, `underline="true"`, `strikethrough="true"`, `code="true"`).
-- Address any node by its `id` attribute from the XML.
-- Edits within a single dispatched batch run **in parallel** against one shared document, so only independent, non-conflicting edits may be batched together.
-
-Your role-specific instructions follow.
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md b/services/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md
index c0895329a9..00cf9c793f 100644
--- a/services/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md
+++ b/services/ai-editing-worker/src/ai-editing/prompts/SUPERVISOR.md
@@ -20,7 +20,6 @@ You should aim to complete the task in few dispatch rounds, and should plan care
You should provide high level English instructions to writers about the changes you want different writers to do. For example, "move paragraph Mz5qcIFm to be right above the q3IMz52m heading." Our writers are non technical and can't understand Markdown or coding terms. Try to avoid telling them *how* to do things. Figuring out how to make changes to documents what they are trained to do.
- Mention existing XML ids for the target region. The writers only get to see context surrounding mentioned nodes.
-- Use native editor objects when appropriate, like dividers, tables, etc. Do not simulate native objects with plain text, like `======` for a divider.
- To mention a person, date/time, document, channel, agent session, or other chip, use the ids and details from the request (userId/email, documentId/documentName/blockName, session id, ISO date plus displayFormat). Date chips do not need a looked-up id. To add a document-card, use the `documentId`/`documentName`/`blockName` from the request. Do not write literal XML/Markdown unless the user wants those literal characters. Do not type `@Name` as plain text when a mention chip exists.
- Do not invent or preserve ids. New ids are assigned automatically and existing ids may change.
- Do not write code yourself; describe the change mechanically.
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/TEAM.md b/services/ai-editing-worker/src/ai-editing/prompts/TEAM.md
new file mode 100644
index 0000000000..545e9d6d73
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/prompts/TEAM.md
@@ -0,0 +1,8 @@
+# How this system works
+
+You are one role in a two-role editing system for handling user requests to edit a document:
+
+- **Supervisor** -- turns the user's request into small, mechanical edit instructions and dispatches them to writers in rounds, reviewing the resulting diff after each round until the request is done.
+- **Writer** -- receives ONE mechanical edit instruction and carries it out by running mechanical document edits.
+
+Edits within a single dispatched batch run **in parallel** against one shared document, so only independent, non-conflicting edits may be batched together.
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/index.ts b/services/ai-editing-worker/src/ai-editing/prompts/index.ts
new file mode 100644
index 0000000000..936756a21e
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/prompts/index.ts
@@ -0,0 +1,53 @@
+/**
+ * System prompts, composed from single-purpose markdown sections.
+ *
+ * Each `.md` file is one section that says one thing; a role's system prompt
+ * is the concatenation below. Keep role files to what is specific to that
+ * role and put anything two roles need in a shared section, so a rule is
+ * written once and every role that edits inherits it.
+ *
+ * - GROUND_RULES: how the document is shown (XML view, ids). Every role.
+ * - TEAM: the supervisor/writer split and parallel batching. Supervised
+ * pipeline roles only — the fast editor works alone.
+ * - EDITING_RULES: how `runCode` and `editor` are used. Anyone who edits.
+ * - API_COMPLETE: the full `editor` API reference. Anyone who edits.
+ * - SUPERVISOR / CODER / FAST / INTERPRET: role-specific text.
+ */
+import API_COMPACT from './API_COMPACT.md';
+import API_COMPLETE from './API_COMPLETE.md';
+import CODER from './CODER.md';
+import EDITING_RULES from './EDITING_RULES.md';
+import FAST from './FAST.md';
+import GROUND_RULES from './GROUND_RULES.md';
+import INTERPRET from './INTERPRET.md';
+import SUPERVISOR from './SUPERVISOR.md';
+import TEAM from './TEAM.md';
+
+// TODO(wolf): figure out if we want this. Leaving it off for now.
+const USE_COMPACT = false;
+
+const join = (...sections: string[]) => sections.join('\n');
+
+export const SUPERVISOR_SYSTEM = join(
+ TEAM,
+ GROUND_RULES,
+ SUPERVISOR,
+ ...(USE_COMPACT ? [API_COMPACT] : [])
+);
+
+export const INTERPRET_SYSTEM = join(TEAM, GROUND_RULES, INTERPRET);
+
+export const CODER_SYSTEM = join(
+ TEAM,
+ GROUND_RULES,
+ CODER,
+ EDITING_RULES,
+ API_COMPLETE
+);
+
+export const FAST_SYSTEM = join(
+ GROUND_RULES,
+ FAST,
+ EDITING_RULES,
+ API_COMPLETE
+);
diff --git a/services/ai-editing-worker/src/ai-editing/prompts/prompts.test.ts b/services/ai-editing-worker/src/ai-editing/prompts/prompts.test.ts
new file mode 100644
index 0000000000..a41c31c698
--- /dev/null
+++ b/services/ai-editing-worker/src/ai-editing/prompts/prompts.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import {
+ CODER_SYSTEM,
+ FAST_SYSTEM,
+ INTERPRET_SYSTEM,
+ SUPERVISOR_SYSTEM,
+} from './index';
+
+describe('composed system prompts', () => {
+ it('every role gets the ground rules exactly once', () => {
+ for (const system of [
+ SUPERVISOR_SYSTEM,
+ INTERPRET_SYSTEM,
+ CODER_SYSTEM,
+ FAST_SYSTEM,
+ ]) {
+ expect(system.match(/read-only structural XML/g)).toHaveLength(1);
+ }
+ });
+
+ it('editing roles share one copy of the editing rules and API', () => {
+ for (const system of [CODER_SYSTEM, FAST_SYSTEM]) {
+ expect(system.match(/## How you write edits/g)).toHaveLength(1);
+ expect(system).toContain('editor.convertToHeading');
+ }
+ expect(SUPERVISOR_SYSTEM).not.toContain('## How you write edits');
+ });
+
+ it('the fast editor is not told it is on a team', () => {
+ expect(FAST_SYSTEM).not.toContain('two-role editing system');
+ expect(FAST_SYSTEM).not.toMatch(/\bsupervisor\b(?! and no other writers)/i);
+ expect(CODER_SYSTEM).toContain('two-role editing system');
+ });
+});
diff --git a/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts b/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts
index 964f6d3bd8..05fed569f4 100644
--- a/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts
+++ b/services/ai-editing-worker/src/ai-editing/tools/dispatch.ts
@@ -8,7 +8,11 @@ import type { Doc } from '../doc';
import type { DocumentOpQueueParams } from '../queue';
import type { TokenTracker } from '../token-tracker';
import { numberLines, serializeWithXml } from '../utils';
-import type { RunCodeToolOptions } from './run-code';
+import {
+ type RunCodeToolOptions,
+ type SnippetPair,
+ snippetsToRecord,
+} from './run-code';
export type { UsageEntry } from '../token-tracker';
export { TokenTracker } from '../token-tracker';
@@ -460,10 +464,18 @@ export function createDispatchTool(opts: DispatchToolOptions) {
if (onCoderResult) {
const codes = result.steps
.flatMap((step) => step.toolCalls)
- .filter((call) => call.toolName === 'runCode')
+ // Schema-rejected calls never ran and carry the model's raw input.
+ .filter((call) => call.toolName === 'runCode' && !call.invalid)
.map((call, i) => {
- const { code, snippets } = call.input as CoderRunCode;
- return { code, snippets, result: entry.trace.runCodeResults[i] };
+ const input = call.input as {
+ code: string;
+ snippets?: SnippetPair[];
+ };
+ return {
+ code: input.code,
+ snippets: snippetsToRecord(input.snippets),
+ result: entry.trace.runCodeResults[i],
+ };
});
onCoderResult(codes);
}
diff --git a/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts b/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts
index 09ad234cd0..9763e21faa 100644
--- a/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts
+++ b/services/ai-editing-worker/src/ai-editing/tools/run-code.test.ts
@@ -14,10 +14,10 @@ import { createRunCodeTool } from './run-code';
* tool call costs the coder its whole step — it has to retry from scratch.
*/
const REAL_PROD_SNIPPETS = {
- 'array of strings (45 of 51 occurrences)': {
- items: ['first list entry', 'second list entry'],
- },
- 'array with a single entry': { listItems: ['only entry'] },
+ 'array of strings (45 of 51 occurrences)': [
+ { key: 'items', text: ['first list entry', 'second list entry'] },
+ ],
+ 'array with a single entry': [{ key: 'items', text: ['only entry'] }],
} as const;
function setup() {
@@ -46,14 +46,22 @@ function schemaOf(tool: ReturnType<typeof createRunCodeTool>) {
}
describe('runCode snippets', () => {
- it('accepts a plain string record', () => {
+ it('accepts a list of string pairs', () => {
const parsed = schemaOf(setup().tool).safeParse({
code: 'editor.setText("a", snippets.body)',
- snippets: { body: 'text' },
+ snippets: [{ key: 'body', text: 'text' }],
});
expect(parsed.success).toBe(true);
});
+ it('rejects the old record shape, which Gemini cannot see the schema of', () => {
+ const parsed = schemaOf(setup().tool).safeParse({
+ code: 'editor.setText("a", snippets.body)',
+ snippets: { body: 'text' },
+ });
+ expect(parsed.success).toBe(false);
+ });
+
for (const [name, snippets] of Object.entries(REAL_PROD_SNIPPETS)) {
it(`accepts ${name}`, () => {
const parsed = schemaOf(setup().tool).safeParse({
@@ -69,7 +77,7 @@ describe('runCode snippets', () => {
await tool.execute!(
{
code: 'editor.setText("a", snippets.items)',
- snippets: { items: ['first', 'second'] },
+ snippets: [{ key: 'items', text: ['first', 'second'] }],
},
callOptions
);
@@ -81,7 +89,10 @@ describe('runCode snippets', () => {
it('leaves string values untouched', async () => {
const { tool, applied } = setup();
await tool.execute!(
- { code: 'editor.setText("a", snippets.body)', snippets: { body: 'x\ny' } },
+ {
+ code: 'editor.setText("a", snippets.body)',
+ snippets: [{ key: 'body', text: 'x\ny' }],
+ },
callOptions
);
expect(applied[0]).toEqual({ body: 'x\ny' });
@@ -90,7 +101,7 @@ describe('runCode snippets', () => {
it('still rejects a value that is neither string nor string[]', () => {
const parsed = schemaOf(setup().tool).safeParse({
code: 'x',
- snippets: { body: { nested: true } },
+ snippets: [{ key: 'body', text: { nested: true } }],
});
expect(parsed.success).toBe(false);
});
diff --git a/services/ai-editing-worker/src/ai-editing/tools/run-code.ts b/services/ai-editing-worker/src/ai-editing/tools/run-code.ts
index acd3659fbe..96c1435779 100644
--- a/services/ai-editing-worker/src/ai-editing/tools/run-code.ts
+++ b/services/ai-editing-worker/src/ai-editing/tools/run-code.ts
@@ -28,19 +28,44 @@ export type RunCodeToolOptions = {
onRunCodeResult?: (result: string) => void;
};
-/** Collapse array snippet values to newline-joined text.
+/**
+ * One snippet as the model sends it. Snippets are a LIST of pairs rather than a
+ * `{ KEY: text }` object because Gemini's function declarations are an OpenAPI
+ * subset with no `additionalProperties`, and the AI SDK's Google provider drops
+ * that field when converting the schema — a record reaches Gemini as an object
+ * with no fields, and it sends `{}` while its code references `snippets.KEY`.
+ * Pairs survive the conversion on every provider we use, so there is one shape
+ * for every agent; the sandbox still sees the record the code indexes into.
*
- * The sandbox exposes `snippets` as a plain object of strings, and every
- * editor primitive takes text, so joining is what the coder wanted anyway when
- * it passed a list. */
-function flattenSnippets(
- snippets: Record<string, string | string[]> | undefined
+ * `text` also accepts a list of strings: coders routinely send an array when
+ * composing list content, and a strict string schema rejected 45 such calls
+ * across the prod corpus, each costing the coder its whole step.
+ */
+const SnippetPairSchema = z.object({
+ key: z.string().describe('the name referenced as `snippets.KEY` in code'),
+ text: z
+ .union([z.string(), z.array(z.string())])
+ .describe('the exact text, unescaped; a list of strings for list content'),
+});
+export type SnippetPair = z.infer<typeof SnippetPairSchema>;
+
+const SnippetsSchema = z
+ .array(SnippetPairSchema)
+ .optional()
+ .describe(
+ 'all text content your code inserts, as a list of { key, text } pairs. reference each as `snippets.KEY` in `code` instead of embedding it as a string literal (avoids escaping errors).'
+ );
+
+/** The record the sandbox exposes as `snippets`; list values join with newlines
+ * since every editor primitive takes text, which is what the coder meant. */
+export function snippetsToRecord(
+ snippets: SnippetPair[] | undefined
): Record<string, string> | undefined {
if (!snippets) return undefined;
return Object.fromEntries(
- Object.entries(snippets).map(([key, value]) => [
+ snippets.map(({ key, text }) => [
key,
- Array.isArray(value) ? value.join('\n') : value,
+ Array.isArray(text) ? text.join('\n') : (text ?? ''),
])
);
}
@@ -54,22 +79,10 @@ export function createRunCodeTool(opts: RunCodeToolOptions) {
"Run JS statements against `editor` (the ONLY in-scope value besides `snippets`) to edit the document — e.g. `editor.convertToHeading('b3', 2); editor.bold('b5', 'word')`. Returns `ok`, or an error naming a bad id so you can retry.",
inputSchema: z.object({
code: z.string(),
- snippets: z
- .record(
- z.string(),
- // Coders routinely send an array when composing a list. A strict
- // string-only record rejected those calls, and the coder's only
- // recourse was to retry the whole step — 45 such retries across the
- // prod corpus. Accept the shape it actually produces.
- z.union([z.string(), z.array(z.string())])
- )
- .optional()
- .describe(
- 'all text content your code inserts: key -> exact content. reference each as `snippets.KEY` in `code` instead of embedding it as a string literal (avoids escaping errors). a value may be an array of strings for list content.'
- ),
+ snippets: SnippetsSchema,
}),
execute: async ({ code, snippets }) => {
- const flattened = flattenSnippets(snippets);
+ const flattened = snippetsToRecord(snippets);
opts.onRunCode?.(flattened);
const span = opts.span
? opts.span.span('edit.run_code')
diff --git a/services/ai-editing-worker/src/endpoints/edit.ts b/services/ai-editing-worker/src/endpoints/edit.ts
index d44676890e..0bdf54ee98 100644
--- a/services/ai-editing-worker/src/endpoints/edit.ts
+++ b/services/ai-editing-worker/src/endpoints/edit.ts
@@ -1,5 +1,6 @@
import { createAnthropic } from '@ai-sdk/anthropic';
import { createCerebras } from '@ai-sdk/cerebras';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
import { createOpenAI } from '@ai-sdk/openai';
import { zValidator } from '@hono/zod-validator';
import { Telemetry } from '@macro-inc/observability';
@@ -8,18 +9,26 @@ import { createFallback } from 'ai-fallback';
import { Hono } from 'hono';
import * as z from 'zod';
import { type Bindings, getEnv } from '../env';
-import { type Model, type ResolvedModels, runEditSession } from '../run-edit';
+import {
+ type EditMode,
+ type Model,
+ type Provider,
+ type ResolvedModels,
+ runEditSession,
+} from '../run-edit';
import { runInSandbox } from '../sandbox';
import { watchPresenceSpeed } from '../service-clients';
import { createWorkerSyncSource } from '../sources';
import { renderTraceMarkdown } from '../trace-log';
import { insertEditTrace } from '../traces-db';
-type Provider = 'anthropic' | 'cerebras' | 'openai';
-
const PROVIDERS = {
anthropic: { key: 'ANTHROPIC_API_KEY', create: createAnthropic },
cerebras: { key: 'CEREBRAS_API_KEY', create: createCerebras },
+ google: {
+ key: 'GOOGLE_GENERATIVE_AI_API_KEY',
+ create: createGoogleGenerativeAI,
+ },
// `.chat()` pins OpenAI to Chat Completions. The default factory uses the
// Responses API, which references reasoning items across steps by id — and
// this org has Zero Data Retention, so those ids are never persisted. Every
@@ -45,7 +54,7 @@ const PROVIDERS = {
>;
const ModelSchema: z.ZodType<Model> = z.object({
- provider: z.enum(['anthropic', 'cerebras', 'openai']),
+ provider: z.enum(['anthropic', 'cerebras', 'openai', 'google']),
model: z.string(),
});
@@ -54,38 +63,72 @@ const ModelSchema: z.ZodType<Model> = z.object({
// rate-limits.
const ModelListSchema = z.array(ModelSchema).min(1);
-const EditBody = z.object({
- documentToken: z.string(),
- documentId: z.string(),
- prompt: z.string(),
- models: z.object({
- supervisor: ModelListSchema,
- interpret: ModelListSchema,
- coding: ModelListSchema,
- }),
- typingAnimations: z.boolean().optional(),
- /** Animation speed multiplier applied while nobody is watching the doc. */
- unwatchedSpeed: z.number().min(1).default(2.0),
- interpret: z.boolean().default(true),
- debug: z.boolean().default(false),
- /**
- * Commit edits to the shared Loro doc (default true). Set false to have the
- * worker compute ops without committing them. This gives you the flexibility
- * to apply them on your own.
- */
- propagate: z.boolean().default(true),
-});
+const EditBody = z
+ .object({
+ documentToken: z.string(),
+ documentId: z.string(),
+ prompt: z.string(),
+ // Each role is a chain; a request only has to name the roles its mode
+ // runs (see the refinements below), and only those are resolved.
+ models: z.object({
+ supervisor: ModelListSchema.optional(),
+ interpret: ModelListSchema.optional(),
+ coding: ModelListSchema.optional(),
+ /** Single-model chain for `mode: 'fast'`. */
+ fast: ModelListSchema.optional(),
+ }),
+ /**
+ * `supervised` (default): interpreter → supervisor → parallel coders.
+ * `fast`: one model, whole document, direct `runCode` — the hot path for
+ * small inline edits. Requires `models.fast`.
+ */
+ mode: z.enum(['supervised', 'fast']).default('supervised'),
+ typingAnimations: z.boolean().optional(),
+ /** Animation speed multiplier applied while nobody is watching the doc. */
+ unwatchedSpeed: z.number().min(1).default(2.0),
+ interpret: z.boolean().default(true),
+ debug: z.boolean().default(false),
+ /**
+ * Commit edits to the shared Loro doc (default true). Set false to have the
+ * worker compute ops without committing them. This gives you the flexibility
+ * to apply them on your own.
+ */
+ propagate: z.boolean().default(true),
+ })
+ .refine((body) => body.mode !== 'fast' || body.models.fast !== undefined, {
+ message: 'mode "fast" requires models.fast',
+ path: ['models', 'fast'],
+ })
+ .refine(
+ (body) =>
+ body.mode !== 'supervised' ||
+ (body.models.supervisor !== undefined &&
+ body.models.interpret !== undefined &&
+ body.models.coding !== undefined),
+ {
+ message:
+ 'mode "supervised" requires models.supervisor, models.interpret, and models.coding',
+ path: ['models'],
+ }
+ );
-/** Resolve each role's model list into a live model (single) or a fallback
- * chain (multiple, advancing on provider errors/rate limits). */
+/** Resolve the mode's model lists into live models (single) or fallback
+ * chains (multiple, advancing on provider errors/rate limits). Roles the mode
+ * does not run are left unresolved, so their providers' keys are never
+ * required. The schema refinements guarantee the mode's roles are present. */
function buildModels(
env: ReturnType<typeof getEnv>,
models: EditModels,
+ mode: EditMode,
onFallback?: () => void
): ResolvedModels {
const resolveOne = ({ provider, model }: Model) => {
- const apiKey = env[PROVIDERS[provider].key];
- return PROVIDERS[provider].create({ apiKey })(model);
+ const { key, create } = PROVIDERS[provider];
+ const apiKey = env[key];
+ if (!apiKey) {
+ throw new Error(`provider "${provider}" requested but ${key} is not set`);
+ }
+ return create({ apiKey })(model);
};
const resolveModel = (specs: Model[]): LanguageModel => {
const resolved = specs.map(resolveOne);
@@ -98,11 +141,18 @@ function buildModels(
},
});
};
+ const required = (role: keyof EditModels): Model[] => {
+ const specs = models[role];
+ if (!specs) throw new Error(`mode "${mode}" requires models.${role}`);
+ return specs;
+ };
+ if (mode === 'fast') return { fast: resolveModel(required('fast')) };
return {
- supervisor: resolveModel(models.supervisor),
- interpret: resolveModel(models.interpret),
- // Fresh fallback per coder — see ResolvedModels.coding.
- coding: () => resolveModel(models.coding),
+ supervised: {
+ supervisor: resolveModel(required('supervisor')),
+ interpret: resolveModel(required('interpret')),
+ coding: () => resolveModel(required('coding')),
+ },
};
}
@@ -117,6 +167,7 @@ edit.post('/', zValidator('json', EditBody), async (c) => {
documentId,
prompt,
models,
+ mode,
typingAnimations,
unwatchedSpeed,
interpret,
@@ -154,6 +205,7 @@ edit.post('/', zValidator('json', EditBody), async (c) => {
'edit.session',
async (span) => {
span.setAttr('document.id', documentId);
+ span.setAttr('edit.mode', mode);
span.setAttr('edit.interpret', interpret);
span.setAttr('edit.propagate', propagate);
let modelFallbacks = 0;
@@ -162,7 +214,8 @@ edit.post('/', zValidator('json', EditBody), async (c) => {
source,
documentId,
prompt,
- models: buildModels(env, models, () => modelFallbacks++),
+ models: buildModels(env, models, mode, () => modelFallbacks++),
+ mode,
typingAnimations,
sleep,
interpret,
diff --git a/services/ai-editing-worker/src/env.ts b/services/ai-editing-worker/src/env.ts
index ae5aa3404f..4c077bd4be 100644
--- a/services/ai-editing-worker/src/env.ts
+++ b/services/ai-editing-worker/src/env.ts
@@ -12,6 +12,8 @@ export type Bindings = {
ANTHROPIC_API_KEY: string | undefined;
CEREBRAS_API_KEY: string | undefined;
OPENAI_API_KEY: string | undefined;
+ /** Optional: only needed when a request names the `google` provider. */
+ GOOGLE_GENERATIVE_AI_API_KEY: string | undefined;
SYNC_WS_BASE: string;
/** D1 database storing edit-session traces. Absent in envs without the binding. */
TRACES_DB: D1Database | undefined;
@@ -29,6 +31,7 @@ function validateEnv(rawEnv: Bindings) {
ANTHROPIC_API_KEY,
CEREBRAS_API_KEY,
OPENAI_API_KEY,
+ GOOGLE_GENERATIVE_AI_API_KEY,
SYNC_WS_BASE,
TRACE_ADMIN_KEY,
INTERNAL_API_KEY,
@@ -38,6 +41,9 @@ function validateEnv(rawEnv: Bindings) {
ANTHROPIC_API_KEY: str({ allowEmpty: false }),
CEREBRAS_API_KEY: str({ allowEmpty: false }),
OPENAI_API_KEY: str({ allowEmpty: false }),
+ // Empty when unset; resolving a `google` model then fails loudly at
+ // request time instead of blocking every other request at boot.
+ GOOGLE_GENERATIVE_AI_API_KEY: str({ default: '', allowEmpty: true }),
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 }),
@@ -49,6 +55,7 @@ function validateEnv(rawEnv: Bindings) {
ANTHROPIC_API_KEY,
CEREBRAS_API_KEY,
OPENAI_API_KEY,
+ GOOGLE_GENERATIVE_AI_API_KEY,
SYNC_WS_BASE,
TRACE_ADMIN_KEY,
INTERNAL_API_KEY,
diff --git a/services/ai-editing-worker/src/run-edit.ts b/services/ai-editing-worker/src/run-edit.ts
index 17965d32e8..26fe5db91a 100644
--- a/services/ai-editing-worker/src/run-edit.ts
+++ b/services/ai-editing-worker/src/run-edit.ts
@@ -12,7 +12,7 @@ import type { SyncServiceSource } from '@macro-inc/collaboration/sync-service/so
import { MARKDOWN_LORO_SCHEMA } from '@macro-inc/lexical-core/markdown-loro-schema';
import { Telemetry } from '@macro-inc/observability';
import type { LanguageModel } from 'ai';
-import { supervisor } from './ai-editing/agents';
+import { fastEditor, supervisor } from './ai-editing/agents';
import type { DocumentOp } from './ai-editing/editor';
import type { CodeRunner } from './ai-editing/runtime';
import type { UsageEntry } from './ai-editing/token-tracker';
@@ -21,29 +21,52 @@ import { serializeWithXml } from './ai-editing/utils';
import { EditingWorkspace } from './editing-workspace';
import { buildTraceSession, type TraceSession } from './trace-log';
+export type Provider = 'anthropic' | 'cerebras' | 'openai' | 'google';
+
export type Model = {
- provider: 'anthropic' | 'cerebras' | 'openai';
+ provider: Provider;
model: string;
};
+/**
+ * `supervised` is the full interpreter → supervisor → coders pipeline.
+ * `fast` skips all of that: one model sees the whole document and edits it
+ * directly through `runCode`. See ai-editing/agents/fast.ts.
+ */
+export type EditMode = 'supervised' | 'fast';
+
export type Models = {
supervisor: Model;
interpret: Model;
coding: Model;
};
-export type ResolvedModels = {
+/** The three roles of the supervised pipeline. */
+export type SupervisedModels = {
supervisor: LanguageModel;
interpret: LanguageModel;
+ /** Fresh fallback chain per coder, so one coder's fallback state does not
+ * leak into a sibling running in parallel. */
coding: () => LanguageModel;
};
+/**
+ * Only the pipeline the request runs is resolved, so a request never touches
+ * a provider it will not call: a supervised edit must not fail because the
+ * fast chain's key is missing, and vice versa.
+ */
+export type ResolvedModels = {
+ supervised?: SupervisedModels;
+ fast?: LanguageModel;
+};
+
export type RunEditArgs = {
/** Live sync source, already constructed by the caller (ws in prod). */
source: SyncServiceSource;
documentId: string;
prompt: string;
models: ResolvedModels;
+ mode?: EditMode;
/** Snippet runner — QuickJS sandbox in prod, `new Function` in local dev. */
runner?: CodeRunner;
typingAnimations?: boolean;
@@ -108,6 +131,10 @@ export async function runEditSession(
// here too would double the content — so route live sync to a no-op sink
// that acks everything and forwards nothing.
const shouldPropagate = args.propagate ?? true;
+ // Typing animations exist for people watching the shared doc. With no
+ // propagation nobody can watch, so every animation pause is pure latency —
+ // measured at 3.4 s of a 6.3 s fast-mode step.
+ const typingAnimations = shouldPropagate ? args.typingAnimations : false;
const liveSource: LiveSyncSource = shouldPropagate
? source
: createNoopLiveSyncSource(args.documentId);
@@ -135,6 +162,16 @@ export async function runEditSession(
const sessionId = crypto.randomUUID();
const startedAt = new Date();
try {
+ const shared = {
+ borrowWriter: () => workspace.borrowWriter(),
+ typingAnimations,
+ sleep: args.sleep,
+ signal: args.signal,
+ runner: args.runner,
+ onOps: (ops: DocumentOp[]) => allOps.push(...ops),
+ onCoderResult: (codes: CoderRunCode[]) => coderCodeBlocks.push([codes]),
+ onEditTrace: (edit: DispatchEditTrace) => dispatchEditTraces.push([edit]),
+ };
const {
totalUsage,
steps,
@@ -142,17 +179,29 @@ export async function runEditSession(
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: (edit) => dispatchEditTraces.push([edit]),
- });
+ } = await (args.mode === 'fast' ? runFast() : runSupervised());
+
+ async function runSupervised() {
+ const models = args.models.supervised;
+ if (!models)
+ throw new Error('supervised mode requires models.supervised');
+ return supervisor(workspace.session, args.prompt, models, {
+ ...shared,
+ interpret: args.interpret,
+ });
+ }
+
+ async function runFast() {
+ const model = args.models.fast;
+ if (!model) throw new Error('fast mode requires models.fast');
+ const result = await fastEditor(
+ workspace.session,
+ args.prompt,
+ model,
+ shared
+ );
+ return { ...result, intent: '', interpretDurationMs: undefined };
+ }
// Drain the queued propagates (plus a final catch-all sync) and ensure every
// commit reached the server before we disconnect. No-op sink when not
diff --git a/services/ai-editing-worker/wrangler.toml b/services/ai-editing-worker/wrangler.toml
index e6614d5664..b5cdc3655e 100644
--- a/services/ai-editing-worker/wrangler.toml
+++ b/services/ai-editing-worker/wrangler.toml
@@ -76,6 +76,7 @@ name = "ai-editing-worker-playground"
[env.playground.vars]
ENVIRONMENT = "development"
+OTEL_EXPORTER_OTLP_ENDPOINT = "https://macro-prox-dev.macroverse.workers.dev/i/otlp/v1/traces"
SYNC_WS_BASE = "wss://sync-service-dev3.macroverse.workers.dev"
DSS_BASE = "https://dev-gateway.macro.com/dss"
SEARCH_SERVICE_BASE = "https://dev-gateway.macro.com/dss"