macroclaw 0.30.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macroclaw",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Telegram-to-Claude-Code bridge",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -130,7 +130,7 @@ const setupCommand = defineCommand({
 	meta: { name: "setup", description: "Run the interactive setup wizard" },
 	args: {
 		"skip-service": { type: "boolean", description: "Skip the service installation prompt" },
-		"install-service": { type: "boolean", description: "Install as a system service without prompting" },
+		"install-service": { type: "boolean", description: "Install as a service without prompting" },
 	},
 	run: ({ args }) => defaultCli.setup({ skipService: args["skip-service"], installService: args["install-service"] }).catch(handleError),
 });
@@ -141,7 +141,7 @@ const claudeCommand = defineCommand({
 });
 
 const serviceInstallCommand = defineCommand({
-	meta: { name: "install", description: "Install and start macroclaw as a system service" },
+	meta: { name: "install", description: "Install and start macroclaw as a service" },
 	args: {
 		token: { type: "string", description: "Claude OAuth token from `claude setup-token` (required on macOS)" },
 	},
@@ -149,17 +149,17 @@ const serviceInstallCommand = defineCommand({
 });
 
 const serviceUninstallCommand = defineCommand({
-	meta: { name: "uninstall", description: "Stop and remove the system service" },
+	meta: { name: "uninstall", description: "Stop and remove the service" },
 	run: () => { try { defaultCli.service("uninstall"); } catch (err) { handleError(err); } },
 });
 
 const serviceStartCommand = defineCommand({
-	meta: { name: "start", description: "Start the system service" },
+	meta: { name: "start", description: "Start the service" },
 	run: () => { try { defaultCli.service("start"); } catch (err) { handleError(err); } },
 });
 
 const serviceStopCommand = defineCommand({
-	meta: { name: "stop", description: "Stop the system service" },
+	meta: { name: "stop", description: "Stop the service" },
 	run: () => { try { defaultCli.service("stop"); } catch (err) { handleError(err); } },
 });
 
@@ -182,7 +182,7 @@ const serviceLogsCommand = defineCommand({
 });
 
 const serviceCommand = defineCommand({
-	meta: { name: "service", description: "Manage macroclaw system service" },
+	meta: { name: "service", description: "Manage macroclaw service" },
 	subCommands: {
 		install: serviceInstallCommand,
 		uninstall: serviceUninstallCommand,

package/src/orchestrator.ts

@@ -9,7 +9,17 @@ import {
 import { writeHistoryPrompt, writeHistoryResult } from "./history";
 import { createLogger } from "./logger";
 import { generateName } from "./naming";
-import { buildEvent, type EventInput, SYSTEM_PROMPT } from "./prompts";
+import {
+  backgroundAgentProgressEvent,
+  backgroundAgentResultEvent,
+  backgroundAgentStartEvent,
+  buttonClickEvent,
+  healthCheckEvent,
+  peekEvent,
+  SYSTEM_PROMPT,
+  scheduleTriggerEvent,
+  userMessageEvent,
+} from "./prompts";
 import { Queue } from "./queue";
 import { loadSessions, saveSessions } from "./sessions";
 
@@ -136,13 +146,11 @@ export class Orchestrator {
 
   handleCron(name: string, prompt: string, model?: string, missed?: { missedBy: string; scheduledAt: string }): void {
     const cronName = `cron-${name}`;
-    const formatted = buildEvent({
-      name: cronName,
-      type: "schedule-trigger",
-      session: "background",
-      schedule: { name, missedBy: missed?.missedBy, scheduledAt: missed?.scheduledAt },
-      text: prompt,
-    });
+    const formatted = scheduleTriggerEvent(
+      cronName,
+      { name, missedBy: missed?.missedBy, scheduledAt: missed?.scheduledAt },
+      prompt,
+    );
     this.#spawnBackgroundRaw(cronName, prompt, formatted, model ?? this.#config.model);
   }
 
@@ -209,13 +217,11 @@ export class Orchestrator {
     this.#callOnResponse({ message: `Peeking at <b>${escapeHtml(session.name)}</b>...` });
 
     try {
-      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 prompt = peekEvent(
+        `peek-${session.name}`,
+        session.name,
+        `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,
         prompt,
@@ -372,56 +378,28 @@ export class Orchestrator {
   }
 
   #formatPrompt(request: OrchestratorRequest, name: string, backgroundedEvent?: string): string {
-    let input: EventInput;
-
     switch (request.type) {
       case "user":
-        input = {
-          name,
-          type: "user-message",
-          session: "main",
-          text: request.message || undefined,
-          files: request.files,
-          backgroundedEvent,
-        };
-        break;
+        return userMessageEvent(name, request.message || "", { files: request.files, backgroundedEvent });
       case "background-agent-result":
-        input = {
+        return backgroundAgentResultEvent(
           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;
+          request.name,
+          { text: request.response.message || "[No output]", files: request.response.files },
+          "Forward this result to the user (action=\"send\"). Summarize or add context from the conversation as appropriate.",
+          { backgroundedEvent },
+        );
       case "background-agent-progress":
-        input = {
+        return backgroundAgentProgressEvent(
           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;
+          request.name,
+          request.progress,
+          "This is an interim progress update, not a final result. Do not report to the user unless it contains exceptionally important information.",
+          { backgroundedEvent },
+        );
       case "button":
-        input = {
-          name,
-          type: "button-click",
-          session: "main",
-          button: request.label,
-          backgroundedEvent,
-        };
-        break;
+        return buttonClickEvent(name, request.label, { backgroundedEvent });
     }
-
-    return buildEvent(input);
   }
 
   static #requestLabel(request: OrchestratorRequest): string {
@@ -455,12 +433,7 @@ export class Orchestrator {
   // --- Background management ---
 
   #spawnBackground(name: string, prompt: string, model: string | undefined) {
-    const formatted = buildEvent({
-      name,
-      type: "background-agent-start",
-      session: "background",
-      text: prompt,
-    });
+    const formatted = backgroundAgentStartEvent(name, prompt);
     this.#spawnBackgroundRaw(name, prompt, formatted, model);
   }
 
@@ -523,13 +496,11 @@ export class Orchestrator {
 
     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.",
-    });
+    const prompt = healthCheckEvent(
+      `health-check-${info.name}`,
+      info.name,
+      "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 {

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>");
   });
 });