macroclaw 0.26.0 → 0.28.0

package/src/prompts.test.ts

@@ -1,16 +1,16 @@
 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");
     expect(SYSTEM_PROMPT).toContain("Files");
-    expect(SYSTEM_PROMPT).toContain("Timeouts");
+    expect(SYSTEM_PROMPT).toContain("Session routing");
   });
 
   it("contains HTML formatting instructions", () => {
@@ -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,243 @@ 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("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;"');
+  });
+});

package/src/prompts.ts

@@ -1,12 +1,3 @@
-export const MAIN_TIMEOUT = 60_000;
-export const CRON_TIMEOUT = 300_000;
-export const BG_TIMEOUT = 1_800_000;
-
-const fmtMin = (ms: number) => {
-  const m = ms / 60_000;
-  return `${m} minute${m > 1 ? "s" : ""}`;
-};
-
 export const SYSTEM_PROMPT = `\
 AI assistant running in macroclaw, an autonomous agent platform. \
 Persistent workspace at cwd with config, memory, skills. \
@@ -24,25 +15,150 @@ Use raw <b>, <i>, <code>, <pre> tags. Escape &, <, > in text content as &amp;, &
 Architecture: message bridge connecting chat interface and scheduled tasks. \
 Persistent session — conversation history carries across messages. Workspace persists across sessions.
 
-Context tags: messages may be prefixed with [Context: <type>]. Types:
-- cron/<name> — automated scheduled task. Prefer action="silent" when nothing noteworthy.
-- button-click — user tapped an inline keyboard button.
-- background-result/<name> — output from a background agent you spawned. Decide whether to relay or handle silently.
-- background-agent/<name> — you are a background agent. Complete task, return result. Cannot spawn sub-agents.
+Event format: every incoming message is wrapped in an <event> XML block. Attributes:
+- name — short identifier for this event (e.g. "check-logs", "cron-daily").
+- type — what triggered this event. One of:
+  - user-message — direct user message. Content in <text>, optional <files>.
+  - button-click — user tapped an inline button. Label in <button>.
+  - schedule-trigger — automated scheduled task. Contains <schedule> with name and optional missed-by/scheduled-at attributes. Prefer action="silent" when nothing noteworthy.
+  - background-agent-start — you are a background agent. Complete the task in <text> and return a result.
+  - background-agent-result — a background agent has finished. Contains <original-event name="..." /> linking to the agent that produced it, and a <result> block with <text> and optional <files>. Always use action="send" — the user expects to see the outcome. Summarize, relay, or add additional context from the conversation as appropriate.
+  - peek — status check on a running session. Contains <target-event name="..." /> identifying the event being peeked at. Only consider progress since that event started. Respond with a brief status update (2-3 sentences): what has been done, what's happening now, what's remaining. Return plain text, not structured output.
+- session — "main" (primary conversation) or "background" (background agent).
+
+Backgrounded events: when a new message arrives while a previous task is still running, \
+the running task is automatically moved to a background session. The new event will contain \
+a <backgrounded-event name="..." /> element referencing the task that was moved. \
+This is informational — the backgrounded task continues running independently. \
+Do not re-execute or act on the backgrounded task; focus on the new event's content.
+
+Inner elements:
+- <text> — the message text or task description.
+- <files> — list of <file path="..." /> attachments. Read/view at those paths.
+- <button> — the label of the tapped button.
+- <schedule> — cron job metadata (name, missed-by, scheduled-at attributes).
+- <backgrounded-event name="..." /> — a previously running task moved to background (see above).
+- <original-event name="..." /> — in background-agent-result, links to the agent that produced the result.
+- <target-event name="..." /> — in peek, identifies the event being checked on.
+- <result> — wraps the output from a completed background agent. Contains <text> and optional <files>.
+- <instructions> — inline guidance for how to handle this specific event. Always follow these instructions.
 
 Background agents: spawn alongside any response via backgroundAgents array:
   backgroundAgents: [{ name: "label", prompt: "task", model: "haiku" }]
-Each runs in same workspace, fresh session. Result fed back as [Context: background-result/<name>].
+Each runs in same workspace, forked session. Result fed back as background-agent-result event.
 Models: haiku (fast/cheap), sonnet (balanced, default), opus (complex reasoning).
-User can spawn directly with "bg:" prefix. Use for long-running tasks that shouldn't block.
+User can spawn directly with /bg command. Use for long-running tasks that shouldn't block.
 
-Files: attachments listed as [File: /path] prefixes. Read/view at those paths. \
-Send files via files array (absolute paths). Images (.png/.jpg/.jpeg/.gif/.webp) as photos, rest as documents. 50MB limit.
+Session routing: if a new message arrives while your session is busy for over 1 minute, \
+the running task is automatically moved to background and a new session is forked. \
+The new event will contain a <backgrounded-event> element (see above).
 
-Timeouts: user=${fmtMin(MAIN_TIMEOUT)}, cron=${fmtMin(CRON_TIMEOUT)}, background=${fmtMin(BG_TIMEOUT)}. \
-On timeout, task continues in background automatically. Spawn background agents proactively for long tasks.
+Files: send files via files array (absolute paths). \
+Images (.png/.jpg/.jpeg/.gif/.webp) as photos, rest as documents. 50MB limit.
 
-Cron: jobs in data/schedule.json (hot-reloaded). Use "silent" when check finds nothing new, "send" when noteworthy.
+Cron: jobs in data/schedule.json (hot-reloaded). Cron jobs always run as background sessions. \
+Use "silent" when check finds nothing new, "send" when noteworthy.
 
 MessageButtons: include a buttons field (flat array of label strings) to attach inline buttons below your message. \
 Each button gets its own row. Max 27 characters per label — if options need more detail, describe them in the message and use short labels on buttons.`;
+
+// --- Event builder ---
+
+export 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"
+  | "peek";
+
+export interface EventInput {
+  name: string;
+  type: EventType;
+  session: SessionType;
+  text?: string;
+  files?: string[];
+  button?: string;
+  schedule?: { name: string; missedBy?: string; scheduledAt?: string };
+  backgroundedEvent?: string;
+  originalEvent?: string;
+  targetEvent?: string;
+  instructions?: string;
+  result?: { text: string; files?: string[] };
+}
+
+export function buildEvent(input: EventInput): string {
+  const lines: string[] = [
+    `<event name="${escapeXml(input.name)}" type="${input.type}" session="${input.session}">`,
+  ];
+
+  // Backgrounded event (always before content for visibility)
+  if (input.backgroundedEvent) {
+    lines.push(`<backgrounded-event name="${escapeXml(input.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)}"`);
+    lines.push(`<schedule ${attrs.join(" ")} />`);
+  }
+
+  // Original event reference (for background-agent-result)
+  if (input.originalEvent) {
+    lines.push(`<original-event name="${escapeXml(input.originalEvent)}" />`);
+  }
+
+  // Target event reference (for peek)
+  if (input.targetEvent) {
+    lines.push(`<target-event name="${escapeXml(input.targetEvent)}" />`);
+  }
+
+  // Result block (for background-agent-result)
+  if (input.result) {
+    lines.push("<result>");
+    lines.push(`<text>${escapeXml(input.result.text)}</text>`);
+    if (input.result.files?.length) {
+      lines.push("<files>");
+      for (const f of input.result.files) {
+        lines.push(`  <file path="${escapeXml(f)}" />`);
+      }
+      lines.push("</files>");
+    }
+    lines.push("</result>");
+  }
+
+  // Button label
+  if (input.button) {
+    lines.push(`<button>${escapeXml(input.button)}</button>`);
+  }
+
+  // Text content
+  if (input.text) {
+    lines.push(`<text>${escapeXml(input.text)}</text>`);
+  }
+
+  // Files
+  if (input.files?.length) {
+    lines.push("<files>");
+    for (const f of input.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>`);
+  }
+
+  lines.push("</event>");
+  return lines.join("\n");
+}

package/src/scheduler.test.ts

@@ -17,7 +17,7 @@ function readScheduleConfig() {
 }
 
 function makeOnJob() {
-	return mock((_name: string, _prompt: string, _model?: string) => {});
+	return mock((_name: string, _prompt: string, _model?: string, _missed?: { missedBy: string; scheduledAt: string }) => {});
 }
 
 // Build a cron expression that matches the current minute
@@ -169,6 +169,7 @@ describe("Scheduler — fireAt jobs", () => {
 		s.stop();
 
 		expect(onJob).toHaveBeenCalledWith("now", "do it", undefined);
+		expect(onJob.mock.calls[0][3]).toBeUndefined();
 	});
 
 	it("removes one-shot job after firing", () => {
@@ -220,9 +221,10 @@ describe("Scheduler — fireAt jobs", () => {
 		expect(onJob).toHaveBeenCalledTimes(1);
 		const call = onJob.mock.calls[0];
 		expect(call[0]).toBe("reminder");
-		expect(call[1]).toContain("[missed event, should have fired");
-		expect(call[1]).toContain("min ago at");
-		expect(call[1]).toContain("buy milk");
+		expect(call[1]).toBe("buy milk");
+		expect(call[3]).toBeDefined();
+		expect(call[3]!.missedBy).toMatch(/^\d+m$/);
+		expect(call[3]!.scheduledAt).toBeDefined();
 	});
 
 	it("removes missed one-shot job after firing", () => {
@@ -257,8 +259,9 @@ describe("Scheduler — fireAt jobs", () => {
 		expect(onJob).toHaveBeenCalledTimes(1);
 		const call = onJob.mock.calls[0];
 		expect(call[0]).toBe("recent");
-		expect(call[1]).toContain("[missed event, should have fired");
-		expect(call[1]).toContain("still valid");
+		expect(call[1]).toBe("still valid");
+		expect(call[3]).toBeDefined();
+		expect(call[3]!.missedBy).toMatch(/^\d+m$/);
 	});
 
 	it("discards stale one-shot job (older than a week) without firing", () => {

package/src/scheduler.ts

@@ -21,8 +21,13 @@ const scheduleConfigSchema = z.object({
 type ScheduleConfig = z.infer<typeof scheduleConfigSchema>;
 type Job = z.infer<typeof jobSchema>;
 
+export interface MissedInfo {
+	missedBy: string;
+	scheduledAt: string;
+}
+
 export interface SchedulerConfig {
-	onJob: (name: string, prompt: string, model?: string) => void;
+	onJob: (name: string, prompt: string, model?: string, missed?: MissedInfo) => void;
 }
 
 const TICK_INTERVAL = 10_000; // 10 seconds
@@ -148,9 +153,11 @@ export class Scheduler {
 
 		if (diff <= MAX_MISSED_MS) {
 			const missedMinutes = Math.round(diff / 60_000);
-			const missedPrompt = `[missed event, should have fired ${missedMinutes} min ago at ${job.fireAt}] ${job.prompt}`;
 			log.info({ name: job.name, missedMinutes, fireAt: job.fireAt }, "Firing missed one-shot job");
-			this.#config.onJob(job.name, missedPrompt, job.model);
+			this.#config.onJob(job.name, job.prompt, job.model, {
+				missedBy: `${missedMinutes}m`,
+				scheduledAt: job.fireAt,
+			});
 			return "remove";
 		}