Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
fix(code-mode): point agents at document edit for text changes (#9859)
Eric Hayes2d5e16c73e88
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.tsindex 38b4589385..d8f3428757 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@@ -16546,7 +16546,9 @@ export interface CodeGuide {** Prefer ExecuteCode for supported Macro work, including a single precise call. Entity indexes in context list each method with its signature. Before writing a program, read the symbols it needs with ReadCodeDocs for their parameters, options and return types, all together in one call, unless their reference is already in context; do not guess option names. Use DescribeCodeTools for the index of an entity not in context or for workflow guides, requesting entities together (e.g. documents, email, ai, core).*- * For editable email/calendar drafts, persist them with execution.reviews.create({kind, title, drafts}), then return reviews: [await review.reference()]. This does not send emails or create calendar events. Creation immediately presents a completed PresentReview ACP tool call, even while main continues. "Presented to the user" means saved in the conversation, not approved or sent. The saved cards remain usable after this execution and chat continues. User decisions arrive as typed system events referring to the same review ID. Use GetReview to read final drafts and confirmed outcomes; notifications never authorize repeating an action. To show the user what the program made, changed or found, present a view with await execution.views.present(view). It is checked and drawn at once, while main continues; nothing is saved and nothing comes back. When to present a view, and its format, are in the PresentView schema at the end of this description. Edit markdown documents and tasks with the SDK document edit(instructions) method. Direct human-interactive tools, subagents and unsupported SDK operations remain available. Never sleep, call setTimeout or poll inside ExecuteCode to wait for something. To check back later, create a routine with a once trigger due shortly, macro.routines.create({trigger: {type: "once", at}, ...}), whose prompt says what to check and where to report, then finish; it runs within about a second of at.+ * For editable email/calendar drafts, persist them with execution.reviews.create({kind, title, drafts}), then return reviews: [await review.reference()]. This does not send emails or create calendar events. Creation immediately presents a completed PresentReview ACP tool call, even while main continues. "Presented to the user" means saved in the conversation, not approved or sent. The saved cards remain usable after this execution and chat continues. User decisions arrive as typed system events referring to the same review ID. Use GetReview to read final drafts and confirmed outcomes; notifications never authorize repeating an action. To show the user what the program made, changed or found, present a view with await execution.views.present(view). It is checked and drawn at once, while main continues; nothing is saved and nothing comes back. When to present a view, and its format, are in the PresentView schema at the end of this description. Direct human-interactive tools, subagents and unsupported SDK operations remain available. Never sleep, call setTimeout or poll inside ExecuteCode to wait for something. To check back later, create a routine with a once trigger due shortly, macro.routines.create({trigger: {type: "once", at}, ...}), whose prompt says what to check and where to report, then finish; it runs within about a second of at.+ *+ * Change the text of existing markdown documents and task bodies in place with the SDK document edit(instructions) method; pass {fast: true} for small edits, because a full edit can take tens of seconds of the execution deadline.** Do the whole job in as few executions as possible, ideally one: every execution costs a model turn. Put control flow in the program instead of checking in one execution and acting in the next, e.g. if macro.tasks.findSimilar finds no likely duplicate, create the task and return it, else return the matches without creating. Use nested SDK entities, e.g. macro.documents.search(query) is an async iterator and document.content() is a promise. Use for await...of, break, conditions and ordinary JavaScript freely. Batch useful independent work with Promise.all or Promise.allSettled; inspect partial failures and await every started operation. Use bounded concurrency for large inputs. Preserve user source scope on every search and retry: macro.documents.search searches documents; macro.email.search searches emails. Read names in batches: macro.initiatives.summaries() and macro.tasks.summaries(tasks) each take one request, while name() on every handle loads each entity separately. Create a task with its initiative, assignees and dueDate in one macro.tasks.create call. Return compact evidence with source IDs, URLs, explicit failures and coverage limits, enough to answer without a follow-up execution; for each item you create or point the user to, return its webUrl() as the URL rather than building one; do not return SDK objects, raw large batches, or claim a stopped iterator is exhaustive.*diff --git a/crates/agent_code_mode/src/inbound/toolset/session/execute_code.md b/crates/agent_code_mode/src/inbound/toolset/session/execute_code.mdindex f301a28c41..df7850c9a1 100644--- a/crates/agent_code_mode/src/inbound/toolset/session/execute_code.md+++ b/crates/agent_code_mode/src/inbound/toolset/session/execute_code.md@@ -2,4 +2,4 @@ Copy turn_id from the current prompt’s hidden invocation context; never substiPrefer ExecuteCode for supported Macro work, including a single precise call. Entity indexes in context list each method with its signature. Before writing a program, read the symbols it needs with ReadCodeDocs for their parameters, options and return types, all together in one call, unless their reference is already in context; do not guess option names. Use DescribeCodeTools for the index of an entity not in context or for workflow guides, requesting entities together (e.g. documents, email, ai, core).-For editable email/calendar drafts, persist them with execution.reviews.create({kind, title, drafts}), then return reviews: [await review.reference()]. This does not send emails or create calendar events. Creation immediately presents a completed PresentReview ACP tool call, even while main continues. "Presented to the user" means saved in the conversation, not approved or sent. The saved cards remain usable after this execution and chat continues. User decisions arrive as typed system events referring to the same review ID. Use GetReview to read final drafts and confirmed outcomes; notifications never authorize repeating an action. To show the user what the program made, changed or found, present a view with await execution.views.present(view). It is checked and drawn at once, while main continues; nothing is saved and nothing comes back. When to present a view, and its format, are in the PresentView schema at the end of this description. Edit markdown documents and tasks with the SDK document edit(instructions) method. Direct human-interactive tools, subagents and unsupported SDK operations remain available. Never sleep, call setTimeout or poll inside ExecuteCode to wait for something. To check back later, create a routine with a once trigger due shortly, macro.routines.create({trigger: {type: "once", at}, ...}), whose prompt says what to check and where to report, then finish; it runs within about a second of at.+For editable email/calendar drafts, persist them with execution.reviews.create({kind, title, drafts}), then return reviews: [await review.reference()]. This does not send emails or create calendar events. Creation immediately presents a completed PresentReview ACP tool call, even while main continues. "Presented to the user" means saved in the conversation, not approved or sent. The saved cards remain usable after this execution and chat continues. User decisions arrive as typed system events referring to the same review ID. Use GetReview to read final drafts and confirmed outcomes; notifications never authorize repeating an action. To show the user what the program made, changed or found, present a view with await execution.views.present(view). It is checked and drawn at once, while main continues; nothing is saved and nothing comes back. When to present a view, and its format, are in the PresentView schema at the end of this description. Direct human-interactive tools, subagents and unsupported SDK operations remain available. Never sleep, call setTimeout or poll inside ExecuteCode to wait for something. To check back later, create a routine with a once trigger due shortly, macro.routines.create({trigger: {type: "once", at}, ...}), whose prompt says what to check and where to report, then finish; it runs within about a second of at.diff --git a/crates/agent_code_mode/src/inbound/toolset/shared/program.md b/crates/agent_code_mode/src/inbound/toolset/shared/program.mdindex 0053eac6af..4ed9dc0324 100644--- a/crates/agent_code_mode/src/inbound/toolset/shared/program.md+++ b/crates/agent_code_mode/src/inbound/toolset/shared/program.md@@ -1,3 +1,5 @@+Change the text of existing markdown documents and task bodies in place with the SDK document edit(instructions) method; pass {fast: true} for small edits, because a full edit can take tens of seconds of the execution deadline.+Do the whole job in as few executions as possible, ideally one: every execution costs a model turn. Put control flow in the program instead of checking in one execution and acting in the next, e.g. if macro.tasks.findSimilar finds no likely duplicate, create the task and return it, else return the matches without creating. Use nested SDK entities, e.g. macro.documents.search(query) is an async iterator and document.content() is a promise. Use for await...of, break, conditions and ordinary JavaScript freely. Batch useful independent work with Promise.all or Promise.allSettled; inspect partial failures and await every started operation. Use bounded concurrency for large inputs. Preserve user source scope on every search and retry: macro.documents.search searches documents; macro.email.search searches emails. Read names in batches: macro.initiatives.summaries() and macro.tasks.summaries(tasks) each take one request, while name() on every handle loads each entity separately. Create a task with its initiative, assignees and dueDate in one macro.tasks.create call. Return compact evidence with source IDs, URLs, explicit failures and coverage limits, enough to answer without a follow-up execution; for each item you create or point the user to, return its webUrl() as the URL rather than building one; do not return SDK objects, raw large batches, or claim a stopped iterator is exhaustive.For a workspace overview, fetch small pages for the relevant categories concurrently in one execution with macro.workspace.page({includeTypes:[type], limit:3}). A single mixed page can be dominated by one category; each page is a sample, not a category total. Return selected metadata and hasMore per category, not whole items or snapshots. Exact workspace types include agent_session, calendar_event, ai_chat and channel_thread. Tasks are documents: use includeTypes:["document"], df:{l:{dst:"task"}}. AST & and | combine exactly two expressions; do not wrap a single filter.diff --git a/packages/code-mode-sdk/src/documentation.test.ts b/packages/code-mode-sdk/src/documentation.test.tsindex 8796c7ca04..25705c2558 100644--- a/packages/code-mode-sdk/src/documentation.test.ts+++ b/packages/code-mode-sdk/src/documentation.test.ts@@ -222,6 +222,7 @@ describe('TypeDoc documentation packaging', () => {);expect(guide('routines')).toContain('never sees this conversation');expect(guide('documents')).toContain('<m-document-mention>');+ expect(guide('documents')).toContain('document.edit(instructions)');expect(guide('search')).toContain('macro.search.all');expect(guide('search')).toContain('macro.documents.search');expect(guide('search')).toContain('macro.workspace.page');diff --git a/packages/sdk/src/entities/documents/document.ts b/packages/sdk/src/entities/documents/document.tsindex 97bef0d2b8..c2f9dd9028 100644--- a/packages/sdk/src/entities/documents/document.ts+++ b/packages/sdk/src/entities/documents/document.ts@@ -117,7 +117,7 @@ export class Document).token;}- /** Prepare multipart content saving and return the service's upload instructions. */+ /** Prepare a multipart file upload; to change a markdown document's text, use `edit`. */async prepareSave(parts: PreSaveDocumentRequest['newBom']) {return unwrap(await this.client.storage.presaveDocumentHandler({@@ -127,7 +127,7 @@ export class Document).data;}- /** Commit uploaded content. Does not retry uncertain writes. */+ /** Commit an uploaded file; to change a markdown document's text, use `edit`. Does not retry uncertain writes. */async save(options: SaveDocumentRequest) {return (await this.mutate((c) =>@@ -139,7 +139,7 @@ export class Document).data;}- /** Commit a simple document save. */+ /** Commit a simple file save; to change a markdown document's text, use `edit`. */async simpleSave() {return (await this.mutate((c) =>@@ -379,9 +379,9 @@ export class Document}/**- * Edit a markdown document or task body by natural-language instructions,- * which an AI editor carries out, merging with anyone editing at the same- * time.+ * Change a markdown document's or task body's text in place: pass+ * natural-language instructions and an AI editor applies them, merging with+ * concurrent edits.** Write instructions like a precise request to a careful editor:* - Say where: name the section or heading, or quote the text to change.diff --git a/packages/sdk/src/entities/documents/namespace.ts b/packages/sdk/src/entities/documents/namespace.tsindex bc43092790..08ca48c5e7 100644--- a/packages/sdk/src/entities/documents/namespace.ts+++ b/packages/sdk/src/entities/documents/namespace.ts@@ -20,6 +20,10 @@ function toBlob(content: FileContent): Blob {* @routing Use when writing, creating, reading or editing a document of any kind, such as a brief, notes, a spec, a canvas, a spreadsheet or a deck; not databases, tasks or email.** @agent+ * ## Changing a document's text+ *+ * Change the text of an existing Markdown document or task body in place, with `document.edit(instructions)` in code or the `EditDocument` tool where code isn't available. Never recreate the document or upload its Markdown to change its text. PDF, Word and other uploaded files can't be edited this way.+ ** ## Linking Macro items inside document content** `CreateDocument` content (the `fileContent` argument) is rendered with the same Markdown parser used for chat responses, channel messages, and email bodies inside the Macro app — but only for Markdown (`.md`) documents. Non-Markdown documents (e.g. PDF, CSV, PNG, XLSX, DOCX, created by passing a non-`md` `file_extension`) are stored as raw file bytes and must never contain Markdown syntax or mention tags.diff --git a/packages/sdk/src/entities/tasks/task.ts b/packages/sdk/src/entities/tasks/task.tsindex 1e55b255ff..853c041198 100644--- a/packages/sdk/src/entities/tasks/task.ts+++ b/packages/sdk/src/entities/tasks/task.ts@@ -53,8 +53,9 @@ export interface SimilarTask {}/**- * A Macro task: a document with sub-type `task`. Inherits the full document- * surface ({@link Document.rename}, move, delete, restore, content, events)+ * A Macro task: a document with sub-type `task`, so every `Document` method+ * works on it, including `content` and `edit` for its body. Inherits the full+ * document surface ({@link Document.rename}, move, delete, restore, events)* and adds task-specific state.*/export class Task extends Document {