macroclaw 0.31.0 → 0.33.0

package/src/prompts.test.ts

@@ -1,5 +1,15 @@
 import { describe, expect, it } from "bun:test";
-import { buildEvent, escapeXml, SYSTEM_PROMPT } from "./prompts";
+import {
+  backgroundAgentProgressEvent,
+  backgroundAgentResultEvent,
+  backgroundAgentStartEvent,
+  buttonClickEvent,
+  healthCheckEvent,
+  peekEvent,
+  SYSTEM_PROMPT,
+  scheduleTriggerEvent,
+  userMessageEvent,
+} from "./prompts";
 
 describe("SYSTEM_PROMPT", () => {
   it("contains key sections", () => {
@@ -50,35 +60,16 @@ describe("SYSTEM_PROMPT", () => {
   });
 });
 
-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", () => {
+describe("userMessageEvent", () => {
   it("builds user message event", () => {
-    const result = buildEvent({
-      name: "check-logs",
-      type: "user-message",
-      session: "main",
-      text: "hello",
-    });
+    const result = userMessageEvent("check-logs", "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?",
+    const result = userMessageEvent("analyze-photo", "what's in this image?", {
       files: ["/tmp/photo.jpg", "/tmp/doc.pdf"],
     });
     expect(result).toContain("<text>what's in this image?</text>");
@@ -88,74 +79,66 @@ describe("buildEvent", () => {
     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",
+    const result = userMessageEvent("check-logs", "check the logs", {
       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",
+    const result = userMessageEvent("check-logs", "hello", {
       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",
+  it("escapes XML in text content", () => {
+    const result = userMessageEvent("test", "a < b & c > d");
+    expect(result).toContain("<text>a &lt; b &amp; c &gt; d</text>");
+  });
+
+  it("escapes XML in name attribute", () => {
+    const result = userMessageEvent('a & "b"', "test");
+    expect(result).toContain('name="a &amp; &quot;b&quot;"');
+  });
+
+  it("escapes XML in backgrounded event name", () => {
+    const result = userMessageEvent("test", "hello", {
+      backgroundedEvent: 'task & "stuff"',
     });
+    expect(result).toContain('backgrounded-event name="task &amp; &quot;stuff&quot;"');
+  });
+});
+
+describe("buttonClickEvent", () => {
+  it("builds button click event", () => {
+    const result = buttonClickEvent("btn-yes", "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",
+    const result = buttonClickEvent("btn-yes", "Yes", {
       backgroundedEvent: "deploy-cluster",
     });
     expect(result).toContain('<backgrounded-event name="deploy-cluster" />');
     expect(result).toContain("<button>Yes</button>");
   });
 
+  it("escapes XML in button label", () => {
+    const result = buttonClickEvent("btn", 'a & "b"');
+    expect(result).toContain("<button>a &amp; &quot;b&quot;</button>");
+  });
+});
+
+describe("scheduleTriggerEvent", () => {
   it("builds schedule trigger event", () => {
-    const result = buildEvent({
-      name: "cron-daily",
-      type: "schedule-trigger",
-      session: "background",
-      schedule: { name: "daily" },
-      text: "check updates",
-    });
+    const result = scheduleTriggerEvent("cron-daily", { name: "daily" }, "check updates");
     expect(result).toContain('type="schedule-trigger"');
     expect(result).toContain('session="background"');
     expect(result).toContain('<schedule name="daily" />');
@@ -163,38 +146,34 @@ describe("buildEvent", () => {
   });
 
   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",
-    });
+    const result = scheduleTriggerEvent(
+      "cron-reminder",
+      { name: "reminder", missedBy: "15m", scheduledAt: "2026-03-20T06:00:00Z" },
+      "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>");
   });
+});
 
+describe("backgroundAgentStartEvent", () => {
   it("builds background agent start event", () => {
-    const result = buildEvent({
-      name: "research",
-      type: "background-agent-start",
-      session: "background",
-      text: "find papers about transformers",
-    });
+    const result = backgroundAgentStartEvent("research", "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>");
   });
+});
 
+describe("backgroundAgentResultEvent", () => {
   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" },
-    });
+    const result = backgroundAgentResultEvent(
+      "bg-research",
+      "research",
+      { text: "found 3 papers" },
+      "Forward to user.",
+    );
     expect(result).toContain('type="background-agent-result"');
     expect(result).toContain('<original-event name="research" />');
     expect(result).toContain("<result>");
@@ -204,102 +183,63 @@ describe("buildEvent", () => {
   });
 
   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"] },
-    });
+    const result = backgroundAgentResultEvent(
+      "bg-research",
+      "research",
+      { text: "here are the screenshots", files: ["/tmp/screenshot.png"] },
+      "Forward to user.",
+    );
     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.",
-    });
+  it("includes instructions after result", () => {
+    const result = backgroundAgentResultEvent(
+      "bg-research",
+      "research",
+      { text: "done" },
+      "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;"');
+describe("backgroundAgentProgressEvent", () => {
+  it("builds progress event with progress tag", () => {
+    const result = backgroundAgentProgressEvent(
+      "progress-research",
+      "research",
+      "indexing 500 documents",
+      "Do not report unless important.",
+    );
+    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("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>");
+describe("peekEvent", () => {
+  it("builds peek event with instructions", () => {
+    const result = peekEvent("peek-deploy", "deploy", "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("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;"');
+describe("healthCheckEvent", () => {
+  it("builds health check event with instructions", () => {
+    const result = healthCheckEvent("health-check-deploy", "deploy", "Report status.");
+    expect(result).toContain('type="health-check"');
+    expect(result).toContain('<target-event name="deploy" />');
+    expect(result).toContain("<instructions>Report status.</instructions>");
   });
 });

package/src/prompts.ts

@@ -67,26 +67,11 @@ Each button gets its own row. Max 27 characters per label — if options need mo
 
 // --- Event builder ---
 
-export function escapeXml(text: string): string {
+function escapeXml(text: string): string {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 
-export type SessionType = "main" | "background";
-
-export type EventType =
-  | "user-message"
-  | "button-click"
-  | "schedule-trigger"
-  | "background-agent-start"
-  | "background-agent-result"
-  | "background-agent-progress"
-  | "peek"
-  | "health-check";
-
-export interface EventInput {
-  name: string;
-  type: EventType;
-  session: SessionType;
+interface BuildXmlFields {
   text?: string;
   files?: string[];
   button?: string;
@@ -99,46 +84,40 @@ export interface EventInput {
   result?: { text: string; files?: string[] };
 }
 
-export function buildEvent(input: EventInput): string {
+function buildXml(name: string, type: string, session: string, fields: BuildXmlFields): string {
   const lines: string[] = [
-    `<event name="${escapeXml(input.name)}" type="${input.type}" session="${input.session}">`,
+    `<event name="${escapeXml(name)}" type="${type}" session="${session}">`,
   ];
 
-  // Backgrounded event (always before content for visibility)
-  if (input.backgroundedEvent) {
-    lines.push(`<backgrounded-event name="${escapeXml(input.backgroundedEvent)}" />`);
+  if (fields.backgroundedEvent) {
+    lines.push(`<backgrounded-event name="${escapeXml(fields.backgroundedEvent)}" />`);
   }
 
-  // Schedule metadata
-  if (input.schedule) {
-    const attrs = [`name="${escapeXml(input.schedule.name)}"`];
-    if (input.schedule.missedBy) attrs.push(`missed-by="${escapeXml(input.schedule.missedBy)}"`);
-    if (input.schedule.scheduledAt) attrs.push(`scheduled-at="${escapeXml(input.schedule.scheduledAt)}"`);
+  if (fields.schedule) {
+    const attrs = [`name="${escapeXml(fields.schedule.name)}"`];
+    if (fields.schedule.missedBy) attrs.push(`missed-by="${escapeXml(fields.schedule.missedBy)}"`);
+    if (fields.schedule.scheduledAt) attrs.push(`scheduled-at="${escapeXml(fields.schedule.scheduledAt)}"`);
     lines.push(`<schedule ${attrs.join(" ")} />`);
   }
 
-  // Original event reference (for background-agent-result)
-  if (input.originalEvent) {
-    lines.push(`<original-event name="${escapeXml(input.originalEvent)}" />`);
+  if (fields.originalEvent) {
+    lines.push(`<original-event name="${escapeXml(fields.originalEvent)}" />`);
   }
 
-  // Target event reference (for peek)
-  if (input.targetEvent) {
-    lines.push(`<target-event name="${escapeXml(input.targetEvent)}" />`);
+  if (fields.targetEvent) {
+    lines.push(`<target-event name="${escapeXml(fields.targetEvent)}" />`);
   }
 
-  // Progress (for background-agent-progress)
-  if (input.progress) {
-    lines.push(`<progress>${escapeXml(input.progress)}</progress>`);
+  if (fields.progress) {
+    lines.push(`<progress>${escapeXml(fields.progress)}</progress>`);
   }
 
-  // Result block (for background-agent-result)
-  if (input.result) {
+  if (fields.result) {
     lines.push("<result>");
-    lines.push(`<text>${escapeXml(input.result.text)}</text>`);
-    if (input.result.files?.length) {
+    lines.push(`<text>${escapeXml(fields.result.text)}</text>`);
+    if (fields.result.files?.length) {
       lines.push("<files>");
-      for (const f of input.result.files) {
+      for (const f of fields.result.files) {
         lines.push(`  <file path="${escapeXml(f)}" />`);
       }
       lines.push("</files>");
@@ -146,30 +125,60 @@ export function buildEvent(input: EventInput): string {
     lines.push("</result>");
   }
 
-  // Button label
-  if (input.button) {
-    lines.push(`<button>${escapeXml(input.button)}</button>`);
+  if (fields.button) {
+    lines.push(`<button>${escapeXml(fields.button)}</button>`);
   }
 
-  // Text content
-  if (input.text) {
-    lines.push(`<text>${escapeXml(input.text)}</text>`);
+  if (fields.text) {
+    lines.push(`<text>${escapeXml(fields.text)}</text>`);
   }
 
-  // Files
-  if (input.files?.length) {
+  if (fields.files?.length) {
     lines.push("<files>");
-    for (const f of input.files) {
+    for (const f of fields.files) {
       lines.push(`  <file path="${escapeXml(f)}" />`);
     }
     lines.push("</files>");
   }
 
-  // Instructions (inline guidance for long sessions)
-  if (input.instructions) {
-    lines.push(`<instructions>${escapeXml(input.instructions)}</instructions>`);
+  if (fields.instructions) {
+    lines.push(`<instructions>${escapeXml(fields.instructions)}</instructions>`);
   }
 
   lines.push("</event>");
   return lines.join("\n");
 }
+
+// --- Per-type event builders ---
+
+export function userMessageEvent(name: string, text: string, opts?: { files?: string[]; backgroundedEvent?: string }): string {
+  return buildXml(name, "user-message", "main", { text, files: opts?.files, backgroundedEvent: opts?.backgroundedEvent });
+}
+
+export function buttonClickEvent(name: string, button: string, opts?: { backgroundedEvent?: string }): string {
+  return buildXml(name, "button-click", "main", { button, backgroundedEvent: opts?.backgroundedEvent });
+}
+
+export function scheduleTriggerEvent(name: string, schedule: { name: string; missedBy?: string; scheduledAt?: string }, text: string): string {
+  return buildXml(name, "schedule-trigger", "background", { schedule, text });
+}
+
+export function backgroundAgentStartEvent(name: string, text: string): string {
+  return buildXml(name, "background-agent-start", "background", { text });
+}
+
+export function backgroundAgentResultEvent(name: string, originalEvent: string, result: { text: string; files?: string[] }, instructions: string, opts?: { backgroundedEvent?: string }): string {
+  return buildXml(name, "background-agent-result", "main", { originalEvent, result, instructions, backgroundedEvent: opts?.backgroundedEvent });
+}
+
+export function backgroundAgentProgressEvent(name: string, originalEvent: string, progress: string, instructions: string, opts?: { backgroundedEvent?: string }): string {
+  return buildXml(name, "background-agent-progress", "main", { originalEvent, progress, instructions, backgroundedEvent: opts?.backgroundedEvent });
+}
+
+export function peekEvent(name: string, targetEvent: string, instructions: string): string {
+  return buildXml(name, "peek", "background", { targetEvent, instructions });
+}
+
+export function healthCheckEvent(name: string, targetEvent: string, instructions: string): string {
+  return buildXml(name, "health-check", "background", { targetEvent, instructions });
+}