macroclaw 0.27.0 → 0.29.0

package/src/orchestrator.ts

@@ -8,7 +8,8 @@ import {
 } from "./claude";
 import { writeHistoryPrompt, writeHistoryResult } from "./history";
 import { createLogger } from "./logger";
-import { SYSTEM_PROMPT } from "./prompts";
+import { generateName } from "./naming";
+import { buildEvent, type EventInput, SYSTEM_PROMPT } from "./prompts";
 import { Queue } from "./queue";
 import { loadSessions, saveSessions } from "./sessions";
 
@@ -19,6 +20,8 @@ const log = createLogger("orchestrator");
 // --- Constants ---
 
 const WAIT_THRESHOLD = 60_000;
+const HEALTH_CHECK_INTERVAL_MS = 5 * 60 * 1000;
+const HEALTH_CHECK_TIMEOUT_MS = 120 * 1000;
 
 // --- Response schema ---
 
@@ -39,7 +42,14 @@ const agentOutputSchema = z.object({
 
 type AgentOutput = z.infer<typeof agentOutputSchema>;
 
+const healthCheckSchema = z.object({
+  finished: z.boolean().describe("True if the task is complete, false if still working"),
+  output: agentOutputSchema.optional().describe("Full output when finished=true"),
+  progress: z.string().optional().describe("One-sentence status when finished=false"),
+});
+
 const responseResultType = { type: "object" as const, schema: agentOutputSchema };
+const healthCheckResultType = { type: "object" as const, schema: healthCheckSchema };
 
 const textResultType = { type: "text" } as const;
 
@@ -58,8 +68,8 @@ export interface OrchestratorResponse {
 
 type OrchestratorRequest =
   | { type: "user"; message: string; files?: string[] }
-  | { type: "cron"; name: string; prompt: string; model?: string }
   | { type: "background-agent-result"; name: string; response: AgentOutput }
+  | { type: "background-agent-progress"; name: string; progress: string }
   | { type: "button"; label: string };
 
 function escapeHtml(text: string): string {
@@ -74,6 +84,7 @@ interface SessionInfo {
   model?: string;
   query: RunningQuery<AgentOutput>;
   lastMessageAt: Date;
+  healthCheckTimer?: Timer;
 }
 
 export interface OrchestratorConfig {
@@ -84,12 +95,18 @@ export interface OrchestratorConfig {
   claude?: Claude;
   /** How long to wait for a running main session before demoting it (ms). Default: 60000 */
   waitThreshold?: number;
+  /** Interval between background agent health checks (ms). Default: 300000. Set to 0 to disable. */
+  healthCheckInterval?: number;
+  /** Timeout for health check fork responses (ms). Default: 120000 */
+  healthCheckTimeout?: number;
 }
 
 export class Orchestrator {
   #config: Omit<OrchestratorConfig , 'claude'>;
   #claude: Claude;
   #waitThreshold: number;
+  #healthCheckInterval: number;
+  #healthCheckTimeout: number;
 
   #mainSessionId: string | undefined;
   #runningSessions = new Map<string, SessionInfo>();
@@ -99,6 +116,8 @@ export class Orchestrator {
     this.#config = config;
     this.#claude = config.claude ?? new Claude({ workspace: config.workspace, systemPrompt: SYSTEM_PROMPT });
     this.#waitThreshold = config.waitThreshold ?? WAIT_THRESHOLD;
+    this.#healthCheckInterval = config.healthCheckInterval ?? HEALTH_CHECK_INTERVAL_MS;
+    this.#healthCheckTimeout = config.healthCheckTimeout ?? HEALTH_CHECK_TIMEOUT_MS;
     this.#queue = new Queue<OrchestratorRequest>();
     this.#queue.setHandler((request) => this.#handleRequest(request));
 
@@ -115,14 +134,20 @@ export class Orchestrator {
     this.#queue.push({ type: "button", label });
   }
 
-  handleCron(name: string, prompt: string, model?: string): void {
+  handleCron(name: string, prompt: string, model?: string, missed?: { missedBy: string; scheduledAt: string }): void {
     const cronName = `cron-${name}`;
-    const cronPrompt = `[Context: cron/${name}] ${prompt}`;
-    this.#spawnBackground(cronName, cronPrompt, model ?? this.#config.model);
+    const formatted = buildEvent({
+      name: cronName,
+      type: "schedule-trigger",
+      session: "background",
+      schedule: { name, missedBy: missed?.missedBy, scheduledAt: missed?.scheduledAt },
+      text: prompt,
+    });
+    this.#spawnBackgroundRaw(cronName, prompt, formatted, model ?? this.#config.model);
   }
 
   handleBackgroundCommand(prompt: string): void {
-    const name = prompt.slice(0, 30).replace(/\s+/g, "-");
+    const name = generateName(prompt);
     this.#spawnBackground(name, prompt, this.#config.model);
     this.#callOnResponse({ message: `Background agent "${escapeHtml(name)}" started.` });
   }
@@ -184,10 +209,16 @@ export class Orchestrator {
     this.#callOnResponse({ message: `Peeking at <b>${escapeHtml(session.name)}</b>...` });
 
     try {
-      const startedAt = session.query.startedAt.toISOString();
+      const prompt = buildEvent({
+        name: `peek-${session.name}`,
+        type: "peek",
+        session: "background",
+        targetEvent: session.name,
+        instructions: `Only consider progress since the "${session.name}" event. Brief status update: done, in progress, remaining. 2-3 sentences max, plain text.`,
+      });
       const query = this.#claude.forkSession(
         sessionId,
-        `This session started at ${startedAt}. Only consider events after that time. Give a brief status update: what has been done so far, what's currently happening, and what's remaining. 2-3 sentences max.`,
+        prompt,
         textResultType,
         { model: "haiku" },
       );
@@ -205,7 +236,7 @@ export class Orchestrator {
       return;
     }
 
-    this.#runningSessions.delete(sessionId);
+    this.#clearSession(sessionId);
 
     try {
       await session.query.kill();
@@ -249,13 +280,12 @@ export class Orchestrator {
 
     await writeHistoryPrompt(request);
 
-    let prompt = this.#formatPrompt(request);
-    if (movedToBackground) {
-      const truncated = movedToBackground.length > 100 ? `${movedToBackground.slice(0, 100)}...` : movedToBackground;
-      prompt = `[Context: previous task "${truncated}" moved to background]\n${prompt}`;
-    }
+    const label = Orchestrator.#requestLabel(request);
+    const name = generateName(label);
+    const backgroundedName = movedToBackground ? mainInfo?.name : undefined;
+    const prompt = this.#formatPrompt(request, name, backgroundedName);
 
-    this.#startMainQuery(prompt, this.#config.model);
+    this.#startMainQuery(name, prompt, this.#config.model);
   }
 
   // --- Response delivery ---
@@ -289,7 +319,7 @@ export class Orchestrator {
 
   // --- Main session query ---
 
-  #startMainQuery(prompt: string, model: string | undefined): void {
+  #startMainQuery(name: string, prompt: string, model: string | undefined): void {
     const opts = { model };
     let query: RunningQuery<AgentOutput>;
 
@@ -302,7 +332,6 @@ export class Orchestrator {
     }
 
     const sid = query.sessionId;
-    const name = prompt.slice(0, 30).replace(/\s+/g, "-");
     this.#runningSessions.set(sid, { name, prompt, model, query, lastMessageAt: new Date() });
 
     if (sid !== this.#mainSessionId) {
@@ -320,7 +349,7 @@ export class Orchestrator {
           await this.#deliverResponse(response);
           return;
         }
-        this.#runningSessions.delete(sid);
+        this.#clearSession(sid);
 
         if (sid === this.#mainSessionId) {
           log.debug({ name, sessionId: sid }, "Main query finished, delivering directly");
@@ -334,7 +363,7 @@ export class Orchestrator {
         if (!this.#runningSessions.has(sid)) {
           log.error({ name, sessionId: sid, err }, "Failed session not in runningSessions — delivering error");
         } else {
-          this.#runningSessions.delete(sid);
+          this.#clearSession(sid);
           log.error({ name, sessionId: sid, err }, "Main query failed");
         }
         await this.#deliverResponse(this.#errorResponse(err));
@@ -342,19 +371,69 @@ export class Orchestrator {
     );
   }
 
-  #formatPrompt(request: OrchestratorRequest): string {
+  #formatPrompt(request: OrchestratorRequest, name: string, backgroundedEvent?: string): string {
+    let input: EventInput;
+
     switch (request.type) {
-      case "user": {
-        if (!request.files?.length) return request.message;
-        const prefix = request.files.map((f) => `[File: ${f}]`).join("\n");
-        return request.message ? `${prefix}\n${request.message}` : prefix;
-      }
-      case "cron":
-        return `[Context: cron/${request.name}] ${request.prompt}`;
+      case "user":
+        input = {
+          name,
+          type: "user-message",
+          session: "main",
+          text: request.message || undefined,
+          files: request.files,
+          backgroundedEvent,
+        };
+        break;
+      case "background-agent-result":
+        input = {
+          name,
+          type: "background-agent-result",
+          session: "main",
+          originalEvent: request.name,
+          result: {
+            text: request.response.message || "[No output]",
+            files: request.response.files,
+          },
+          backgroundedEvent,
+          instructions: "Forward this result to the user (action=\"send\"). Summarize or add context from the conversation as appropriate.",
+        };
+        break;
+      case "background-agent-progress":
+        input = {
+          name,
+          type: "background-agent-progress",
+          session: "main",
+          originalEvent: request.name,
+          progress: request.progress,
+          instructions: "This is an interim progress update, not a final result. Do not report to the user unless it contains exceptionally important information.",
+          backgroundedEvent,
+        };
+        break;
+      case "button":
+        input = {
+          name,
+          type: "button-click",
+          session: "main",
+          button: request.label,
+          backgroundedEvent,
+        };
+        break;
+    }
+
+    return buildEvent(input);
+  }
+
+  static #requestLabel(request: OrchestratorRequest): string {
+    switch (request.type) {
+      case "user":
+        return request.message;
       case "background-agent-result":
-        return `[Context: background-result/${request.name}] ${request.response.message || "[No output]"}`;
+        return `bg:${request.name}`;
+      case "background-agent-progress":
+        return `progress:${request.name}`;
       case "button":
-        return `[Context: button-click] User tapped "${request.label}"`;
+        return `btn:${request.label}`;
     }
   }
 
@@ -376,32 +455,126 @@ export class Orchestrator {
   // --- Background management ---
 
   #spawnBackground(name: string, prompt: string, model: string | undefined) {
-    const bgPrompt = `[Context: background-agent/${name}] ${prompt}`;
+    const formatted = buildEvent({
+      name,
+      type: "background-agent-start",
+      session: "background",
+      text: prompt,
+    });
+    this.#spawnBackgroundRaw(name, prompt, formatted, model);
+  }
+
+  #spawnBackgroundRaw(name: string, prompt: string, formatted: string, model: string | undefined) {
     const query = this.#mainSessionId
-      ? this.#claude.forkSession(this.#mainSessionId, bgPrompt, responseResultType, { model })
-      : this.#claude.newSession(bgPrompt, responseResultType, { model });
+      ? this.#claude.forkSession(this.#mainSessionId, formatted, responseResultType, { model })
+      : this.#claude.newSession(formatted, responseResultType, { model });
     this.#registerBackground(name, prompt, model, query);
   }
 
   #registerBackground(name: string, prompt: string, model: string | undefined, query: RunningQuery<AgentOutput>) {
     const sid = query.sessionId;
-    this.#runningSessions.set(sid, { name, prompt, model, query, lastMessageAt: new Date() });
+    const info: SessionInfo = { name, prompt, model, query, lastMessageAt: new Date() };
+    this.#runningSessions.set(sid, info);
 
     log.debug({ name, sessionId: sid }, "Background session registered");
 
+    this.#scheduleHealthCheck(sid);
+
     query.result.then(
       ({ value: response }) => {
         if (!this.#runningSessions.has(sid)) return;
-        this.#runningSessions.delete(sid);
+        this.#clearSession(sid);
         log.debug({ name, message: response.message }, "Background session finished");
         this.#queue.push({ type: "background-agent-result", name, response });
       },
       (err) => {
         if (!this.#runningSessions.has(sid)) return;
-        this.#runningSessions.delete(sid);
+        this.#clearSession(sid);
         log.error({ name, err }, "Background session failed");
         this.#queue.push({ type: "background-agent-result", name, response: { action: "send", message: `[Error] ${err}`, actionReason: "bg-failed" } });
       },
     );
   }
+
+  // --- Session cleanup ---
+
+  #clearSession(sessionId: string) {
+    const info = this.#runningSessions.get(sessionId);
+    if (info?.healthCheckTimer) clearTimeout(info.healthCheckTimer);
+    this.#runningSessions.delete(sessionId);
+  }
+
+  // --- Health checks ---
+
+  #scheduleHealthCheck(sessionId: string) {
+    if (this.#healthCheckInterval <= 0) return;
+
+    const info = this.#runningSessions.get(sessionId);
+    if (!info) return;
+
+    info.healthCheckTimer = setTimeout(() => {
+      this.#runHealthCheck(sessionId);
+    }, this.#healthCheckInterval);
+  }
+
+  async #runHealthCheck(sessionId: string): Promise<void> {
+    const info = this.#runningSessions.get(sessionId);
+    if (!info) return;
+
+    log.debug({ name: info.name, sessionId }, "Running health check");
+
+    const prompt = buildEvent({
+      name: `health-check-${info.name}`,
+      type: "health-check",
+      session: "background",
+      targetEvent: info.name,
+      instructions: "Report your current status. If your task is complete, set finished=true and provide the full output. If still working, set finished=false and describe current progress in one sentence.",
+    });
+
+    let query: RunningQuery<z.infer<typeof healthCheckSchema>>;
+    try {
+      query = this.#claude.forkSession(sessionId, prompt, healthCheckResultType, { model: "haiku" });
+    } catch (err) {
+      log.error({ name: info.name, sessionId, err }, "Health check fork failed");
+      this.#scheduleHealthCheck(sessionId);
+      return;
+    }
+
+    const result = await Promise.race([
+      query.result.then((r) => r.value),
+      new Promise<"timeout">((r) => setTimeout(() => r("timeout"), this.#healthCheckTimeout)),
+    ]);
+
+    // Session may have completed/been killed while health check was running
+    if (!this.#runningSessions.has(sessionId)) return;
+
+    if (result === "timeout") {
+      log.warn({ name: info.name, sessionId }, "Health check timed out, killing session");
+      try { await query.kill(); } catch { /* ignore */ }
+      this.#clearSession(sessionId);
+      try { await info.query.kill(); } catch { /* ignore */ }
+      this.#callOnResponse({ message: `Agent <b>${escapeHtml(info.name)}</b> appears unresponsive, killed it.` });
+      return;
+    }
+
+    if (result.finished) {
+      log.info({ name: info.name, sessionId }, "Health check: agent reports finished");
+      this.#clearSession(sessionId);
+      try { await info.query.kill(); } catch { /* ignore */ }
+      const response = result.output ?? { action: "send" as const, message: "[Agent finished but returned no output]", actionReason: "health-check-finished" };
+      this.#queue.push({ type: "background-agent-result", name: info.name, response });
+      return;
+    }
+
+    log.debug({ name: info.name, progress: result.progress }, "Health check: still running");
+    if (result.progress) {
+      this.#queue.push({
+        type: "background-agent-progress",
+        name: info.name,
+        progress: result.progress,
+      });
+    }
+
+    this.#scheduleHealthCheck(sessionId);
+  }
 }

package/src/prompts.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from "bun:test";
-import { SYSTEM_PROMPT } from "./prompts";
+import { buildEvent, escapeXml, SYSTEM_PROMPT } from "./prompts";
 
 describe("SYSTEM_PROMPT", () => {
   it("contains key sections", () => {
     expect(SYSTEM_PROMPT).toContain("macroclaw");
     expect(SYSTEM_PROMPT).toContain("Structured output");
-    expect(SYSTEM_PROMPT).toContain("Context tags");
+    expect(SYSTEM_PROMPT).toContain("Event format");
     expect(SYSTEM_PROMPT).toContain("Background agents");
     expect(SYSTEM_PROMPT).toContain("Cron");
     expect(SYSTEM_PROMPT).toContain("Buttons");
@@ -18,11 +18,19 @@ describe("SYSTEM_PROMPT", () => {
     expect(SYSTEM_PROMPT).toContain("<b>");
   });
 
-  it("documents all context tag types", () => {
-    expect(SYSTEM_PROMPT).toContain("cron/<name>");
+  it("documents all event types", () => {
+    expect(SYSTEM_PROMPT).toContain("user-message");
     expect(SYSTEM_PROMPT).toContain("button-click");
-    expect(SYSTEM_PROMPT).toContain("background-result/<name>");
-    expect(SYSTEM_PROMPT).toContain("background-agent/<name>");
+    expect(SYSTEM_PROMPT).toContain("schedule-trigger");
+    expect(SYSTEM_PROMPT).toContain("background-agent-start");
+    expect(SYSTEM_PROMPT).toContain("background-agent-result");
+    expect(SYSTEM_PROMPT).toContain("peek");
+  });
+
+  it("documents backgrounded events", () => {
+    expect(SYSTEM_PROMPT).toContain("backgrounded-event");
+    expect(SYSTEM_PROMPT).toContain("moved to background");
+    expect(SYSTEM_PROMPT).toContain("Do not re-execute");
   });
 
   it("contains structured output reinforcement", () => {
@@ -41,3 +49,257 @@ describe("SYSTEM_PROMPT", () => {
     expect(SYSTEM_PROMPT).toContain("opus");
   });
 });
+
+describe("escapeXml", () => {
+  it("escapes &, <, >, \"", () => {
+    expect(escapeXml('a & b < c > d "e"')).toBe("a &amp; b &lt; c &gt; d &quot;e&quot;");
+  });
+
+  it("returns plain text unchanged", () => {
+    expect(escapeXml("hello world")).toBe("hello world");
+  });
+});
+
+describe("buildEvent", () => {
+  it("builds user message event", () => {
+    const result = buildEvent({
+      name: "check-logs",
+      type: "user-message",
+      session: "main",
+      text: "hello",
+    });
+    expect(result).toStartWith('<event name="check-logs" type="user-message" session="main">');
+    expect(result).toContain("<text>hello</text>");
+    expect(result).toEndWith("</event>");
+  });
+
+  it("builds user message with files", () => {
+    const result = buildEvent({
+      name: "analyze-photo",
+      type: "user-message",
+      session: "main",
+      text: "what's in this image?",
+      files: ["/tmp/photo.jpg", "/tmp/doc.pdf"],
+    });
+    expect(result).toContain("<text>what's in this image?</text>");
+    expect(result).toContain("<files>");
+    expect(result).toContain('<file path="/tmp/photo.jpg" />');
+    expect(result).toContain('<file path="/tmp/doc.pdf" />');
+    expect(result).toContain("</files>");
+  });
+
+  it("builds user message with files only (no text)", () => {
+    const result = buildEvent({
+      name: "task",
+      type: "user-message",
+      session: "main",
+      files: ["/tmp/photo.jpg"],
+    });
+    expect(result).not.toContain("<text>");
+    expect(result).toContain('<file path="/tmp/photo.jpg" />');
+  });
+
+  it("builds user message with backgrounded event", () => {
+    const result = buildEvent({
+      name: "check-logs",
+      type: "user-message",
+      session: "main",
+      backgroundedEvent: "deploy-cluster",
+      text: "check the logs",
+    });
+    expect(result).toContain('<backgrounded-event name="deploy-cluster" />');
+    expect(result).toContain("<text>check the logs</text>");
+  });
+
+  it("places backgrounded-event before text", () => {
+    const result = buildEvent({
+      name: "check-logs",
+      type: "user-message",
+      session: "main",
+      backgroundedEvent: "deploy",
+      text: "hello",
+    });
+    const bgIdx = result.indexOf("backgrounded-event");
+    const textIdx = result.indexOf("<text>");
+    expect(bgIdx).toBeLessThan(textIdx);
+  });
+
+  it("builds button click event", () => {
+    const result = buildEvent({
+      name: "btn-yes",
+      type: "button-click",
+      session: "main",
+      button: "Yes",
+    });
+    expect(result).toContain('type="button-click"');
+    expect(result).toContain("<button>Yes</button>");
+    expect(result).not.toContain("<text>");
+  });
+
+  it("builds button click with backgrounded event", () => {
+    const result = buildEvent({
+      name: "btn-yes",
+      type: "button-click",
+      session: "main",
+      button: "Yes",
+      backgroundedEvent: "deploy-cluster",
+    });
+    expect(result).toContain('<backgrounded-event name="deploy-cluster" />');
+    expect(result).toContain("<button>Yes</button>");
+  });
+
+  it("builds schedule trigger event", () => {
+    const result = buildEvent({
+      name: "cron-daily",
+      type: "schedule-trigger",
+      session: "background",
+      schedule: { name: "daily" },
+      text: "check updates",
+    });
+    expect(result).toContain('type="schedule-trigger"');
+    expect(result).toContain('session="background"');
+    expect(result).toContain('<schedule name="daily" />');
+    expect(result).toContain("<text>check updates</text>");
+  });
+
+  it("builds missed schedule trigger with attributes", () => {
+    const result = buildEvent({
+      name: "cron-reminder",
+      type: "schedule-trigger",
+      session: "background",
+      schedule: { name: "reminder", missedBy: "15m", scheduledAt: "2026-03-20T06:00:00Z" },
+      text: "buy milk",
+    });
+    expect(result).toContain('missed-by="15m"');
+    expect(result).toContain('scheduled-at="2026-03-20T06:00:00Z"');
+    expect(result).toContain("<text>buy milk</text>");
+  });
+
+  it("builds background agent start event", () => {
+    const result = buildEvent({
+      name: "research",
+      type: "background-agent-start",
+      session: "background",
+      text: "find papers about transformers",
+    });
+    expect(result).toContain('type="background-agent-start"');
+    expect(result).toContain('session="background"');
+    expect(result).toContain("<text>find papers about transformers</text>");
+  });
+
+  it("builds background agent result (text only)", () => {
+    const result = buildEvent({
+      name: "bg-research",
+      type: "background-agent-result",
+      session: "main",
+      originalEvent: "research",
+      result: { text: "found 3 papers" },
+    });
+    expect(result).toContain('type="background-agent-result"');
+    expect(result).toContain('<original-event name="research" />');
+    expect(result).toContain("<result>");
+    expect(result).toContain("<text>found 3 papers</text>");
+    expect(result).toContain("</result>");
+    expect(result).not.toContain("<files>");
+  });
+
+  it("builds background agent result with files", () => {
+    const result = buildEvent({
+      name: "bg-research",
+      type: "background-agent-result",
+      session: "main",
+      originalEvent: "research",
+      result: { text: "here are the screenshots", files: ["/tmp/screenshot.png"] },
+    });
+    expect(result).toContain("<result>");
+    expect(result).toContain("<text>here are the screenshots</text>");
+    expect(result).toContain('<file path="/tmp/screenshot.png" />');
+    expect(result).toContain("</result>");
+  });
+
+  it("builds peek event with instructions", () => {
+    const result = buildEvent({
+      name: "peek-deploy",
+      type: "peek",
+      session: "background",
+      targetEvent: "deploy",
+      instructions: "Brief status update.",
+    });
+    expect(result).toContain('type="peek"');
+    expect(result).toContain('<target-event name="deploy" />');
+    expect(result).toContain("<instructions>Brief status update.</instructions>");
+    expect(result).not.toContain("<text>");
+  });
+
+  it("builds progress event with progress tag", () => {
+    const result = buildEvent({
+      name: "progress-research",
+      type: "background-agent-progress",
+      session: "main",
+      originalEvent: "research",
+      progress: "indexing 500 documents",
+    });
+    expect(result).toContain('type="background-agent-progress"');
+    expect(result).toContain('<original-event name="research" />');
+    expect(result).toContain("<progress>indexing 500 documents</progress>");
+    expect(result).not.toContain("<result>");
+  });
+
+  it("includes instructions in event", () => {
+    const result = buildEvent({
+      name: "bg-research",
+      type: "background-agent-result",
+      session: "main",
+      originalEvent: "research",
+      result: { text: "done" },
+      instructions: "Forward to user.",
+    });
+    expect(result).toContain("<instructions>Forward to user.</instructions>");
+    // instructions come last, before </event>
+    const instrIdx = result.indexOf("<instructions>");
+    const closeIdx = result.indexOf("</event>");
+    expect(instrIdx).toBeLessThan(closeIdx);
+    expect(instrIdx).toBeGreaterThan(result.indexOf("</result>"));
+  });
+
+  it("escapes XML in text content", () => {
+    const result = buildEvent({
+      name: "test",
+      type: "user-message",
+      session: "main",
+      text: "a < b & c > d",
+    });
+    expect(result).toContain("<text>a &lt; b &amp; c &gt; d</text>");
+  });
+
+  it("escapes XML in name attribute", () => {
+    const result = buildEvent({
+      name: 'a & "b"',
+      type: "user-message",
+      session: "main",
+      text: "test",
+    });
+    expect(result).toContain('name="a &amp; &quot;b&quot;"');
+  });
+
+  it("escapes XML in button label", () => {
+    const result = buildEvent({
+      name: "btn",
+      type: "button-click",
+      session: "main",
+      button: 'a & "b"',
+    });
+    expect(result).toContain("<button>a &amp; &quot;b&quot;</button>");
+  });
+
+  it("escapes XML in backgrounded event name", () => {
+    const result = buildEvent({
+      name: "test",
+      type: "user-message",
+      session: "main",
+      backgroundedEvent: 'task & "stuff"',
+      text: "hello",
+    });
+    expect(result).toContain('backgrounded-event name="task &amp; &quot;stuff&quot;"');
+  });
+});