macroclaw 0.27.0 → 0.28.0

package/package.json

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

package/src/app.test.ts

@@ -166,7 +166,7 @@ describe("App", () => {
       await new Promise((r) => setTimeout(r, 50));
 
       const claude = config.claude as Claude & { calls: CallInfo[] };
-      expect(claude.calls[0].prompt).toBe("hello");
+      expect(claude.calls[0].prompt).toContain("<text>hello</text>");
     });
 
     it("ignores messages from unauthorized chats", async () => {
@@ -219,7 +219,7 @@ describe("App", () => {
       await new Promise((r) => setTimeout(r, 50));
 
       const claude = config.claude as Claude & { calls: CallInfo[] };
-      expect(claude.calls[0].prompt).toBe("bg: research pricing");
+      expect(claude.calls[0].prompt).toContain("<text>bg: research pricing</text>");
     });
 
     it("sends error wrapped in response", async () => {
@@ -269,7 +269,7 @@ describe("App", () => {
       expect(bot.api.getFile).toHaveBeenCalledWith("large");
       const claude = config.claude as Claude & { calls: CallInfo[] };
       expect(claude.calls).toHaveLength(1);
-      expect(claude.calls[0].prompt).toContain("[File:");
+      expect(claude.calls[0].prompt).toContain("<file path=");
 
       globalThis.fetch = origFetch;
     });
@@ -297,7 +297,7 @@ describe("App", () => {
       expect(bot.api.getFile).toHaveBeenCalledWith("doc-id");
       const claude = config.claude as Claude & { calls: CallInfo[] };
       expect(claude.calls).toHaveLength(1);
-      expect(claude.calls[0].prompt).toContain("[File:");
+      expect(claude.calls[0].prompt).toContain("<file path=");
 
       globalThis.fetch = origFetch;
     });
@@ -363,7 +363,7 @@ describe("App", () => {
 
       const claude = config.claude as Claude & { calls: CallInfo[] };
       expect(claude.calls).toHaveLength(1);
-      expect(claude.calls[0].prompt).toBe("hello from voice");
+      expect(claude.calls[0].prompt).toContain("<text>hello from voice</text>");
 
       globalThis.fetch = origFetch;
     });
@@ -532,7 +532,7 @@ describe("App", () => {
       expect(ctx.editMessageReplyMarkup).toHaveBeenCalledWith({ reply_markup: { inline_keyboard: [[{ text: "✓ Yes", callback_data: "_noop" }]] } });
       const claude = config.claude as Claude & { calls: CallInfo[] };
       expect(claude.calls).toHaveLength(1);
-      expect(claude.calls[0].prompt).toBe('[Context: button-click] User tapped "Yes"');
+      expect(claude.calls[0].prompt).toContain('<button>Yes</button>');
     });
 
     it("handles _dismiss callback by removing reply markup", async () => {
@@ -688,7 +688,7 @@ describe("App", () => {
 
       expect((config.claude as Claude & { calls: CallInfo[] }).calls).toHaveLength(0);
       const calls = (bot.api.sendMessage as any).mock.calls;
-      expect(calls[calls.length - 1][1]).toBe("Usage: /bg <prompt>");
+      expect(calls[calls.length - 1][1]).toBe("Usage: /bg &lt;prompt&gt;");
     });
 
     it("/bg with prompt spawns a background agent via sendMessage", async () => {

package/src/app.ts

@@ -43,7 +43,7 @@ export class App {
   start() {
     log.info("Starting macroclaw...");
     const scheduler = new Scheduler(this.#config.workspace, {
-      onJob: (name, prompt, model) => this.#orchestrator.handleCron(name, prompt, model),
+      onJob: (name, prompt, model, missed) => this.#orchestrator.handleCron(name, prompt, model, missed),
     });
     scheduler.start();
     this.#bot.api.setMyCommands([
@@ -78,7 +78,7 @@ export class App {
       const prompt = ctx.match?.trim();
       if (!prompt) {
         log.debug("Command /bg without prompt");
-        sendResponse(this.#bot, this.#config.authorizedChatId, "Usage: /bg <prompt>");
+        sendResponse(this.#bot, this.#config.authorizedChatId, "Usage: /bg &lt;prompt&gt;");
         return;
       }
       log.debug({ prompt }, "Command /bg spawn");

package/src/claude.ts

@@ -123,7 +123,7 @@ export class Claude {
     if (systemPrompt) args.push("--append-system-prompt", systemPrompt);
     args.push(prompt);
 
-    log.debug({ model, sessionId, promptLen: prompt.length, mode: mode.kind, hasSystemPrompt: !!systemPrompt }, "Sending to Claude");
+    log.debug({ model, sessionId, promptLen: prompt.length, mode: mode.kind, hasSystemPrompt: !!systemPrompt, prompt }, "Sending to Claude");
 
     const proc = Bun.spawn(args, { cwd: this.#workspace, env, stdout: "pipe", stderr: "pipe" });
     const startedAt = new Date();

package/src/index.ts

@@ -8,6 +8,10 @@ import { SpeechToText } from "./speech-to-text";
 export async function start(): Promise<void> {
   const log = createLogger("index");
 
+  process.on("unhandledRejection", (err) => {
+    log.error({ err }, "Unhandled rejection");
+  });
+
   const mgr = new SettingsManager();
   const settings = mgr.load();
   const { settings: resolved, overrides } = mgr.applyEnvOverrides(settings);

package/src/naming.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { generateName } from "./naming";
+
+describe("generateName", () => {
+  test("extracts content words from English prompt", () => {
+    expect(generateName("please research the best coffee shops in Prague")).toBe("research-best-coffee-shops");
+  });
+
+  test("extracts content words from Czech prompt", () => {
+    expect(generateName("najdi nejlepsi kavárny v Praze a porovnej ceny")).toBe("najdi-nejlepsi-kavrny-praze");
+  });
+
+  test("returns 'task' for stop-words-only prompt", () => {
+    expect(generateName("please do this for me")).toBe("task");
+  });
+
+  test("returns 'task' for empty prompt", () => {
+    expect(generateName("")).toBe("task");
+  });
+
+  test("strips non-alphanumeric characters", () => {
+    expect(generateName("fix bug #123 in auth-service!")).toBe("fix-bug-123-auth");
+  });
+
+  test("respects maxWords parameter", () => {
+    expect(generateName("deploy new redis cluster with monitoring", 2)).toBe("deploy-new");
+  });
+
+  test("skips single-character words", () => {
+    expect(generateName("a b c deploy x y z")).toBe("deploy");
+  });
+
+  test("handles mixed English and Czech", () => {
+    expect(generateName("zkontroluj jestli je deploy hotovy")).toBe("zkontroluj-jestli-deploy-hotovy");
+  });
+
+  test("respects maxLength and drops words that would exceed it", () => {
+    expect(generateName("deploy infrastructure monitoring cluster", 4, 25)).toBe("deploy-infrastructure");
+  });
+
+  test("returns 'task' for very long single nonsense word", () => {
+    expect(generateName("a".repeat(500))).toBe("task");
+  });
+});

package/src/naming.ts

@@ -0,0 +1,54 @@
+/** Generates a short kebab-case name from a prompt by extracting content words. */
+
+const STOP_WORDS = new Set([
+  // English
+  "a", "about", "above", "after", "again", "all", "also", "am", "an", "and",
+  "any", "are", "as", "at", "be", "because", "been", "before", "being",
+  "between", "both", "but", "by", "can", "could", "did", "do", "does",
+  "doing", "down", "during", "each", "few", "for", "from", "further", "get",
+  "got", "had", "has", "have", "having", "he", "her", "here", "hers",
+  "herself", "him", "himself", "his", "how", "i", "if", "in", "into", "is",
+  "it", "its", "itself", "just", "know", "let", "like", "make", "may", "me",
+  "might", "more", "most", "must", "my", "myself", "need", "no", "nor", "not",
+  "now", "of", "off", "on", "once", "only", "or", "other", "our", "ours",
+  "ourselves", "out", "over", "own", "please", "really", "right", "same",
+  "shall", "she", "should", "so", "some", "such", "take", "than", "that",
+  "the", "their", "theirs", "them", "themselves", "then", "there", "these",
+  "they", "this", "those", "through", "to", "too", "under", "until", "up",
+  "us", "very", "want", "was", "we", "were", "what", "when", "where", "which",
+  "while", "who", "whom", "why", "will", "with", "would", "you", "your",
+  "yours", "yourself", "yourselves",
+  // Czech
+  "a", "aby", "aj", "ale", "ani", "ano", "asi", "az", "bez", "bude", "budem",
+  "budes", "by", "byl", "byla", "byli", "bylo", "byt", "ci", "co", "dal",
+  "dane", "do", "ho", "i", "ja", "jak", "jako", "je", "jeho", "jej", "jeji",
+  "jen", "jeste", "ji", "jich", "jim", "jine", "jiz", "jsem", "jses", "jsi",
+  "jsme", "jsou", "jste", "k", "kam", "kde", "kdo", "kdyz", "ke", "ktera",
+  "ktere", "kteri", "kterou", "ktery", "ma", "mam", "mate", "me", "mezi",
+  "mi", "mit", "mne", "mnou", "moc", "moje", "moji", "mu", "muze", "my",
+  "na", "nad", "nam", "nami", "nas", "nasi", "ne", "nebo", "nebot", "necht",
+  "nejsou", "neni", "nez", "nic", "nim", "o", "od", "on", "ona", "oni",
+  "ono", "pak", "po", "pod", "podle", "pokud", "potom", "pouze", "prave",
+  "pro", "proc", "proto", "protoze", "prvni", "pred", "presto", "pri", "sam",
+  "se", "si", "sice", "sve", "svou", "svuj", "svych", "svym", "svymi", "ta",
+  "tak", "take", "takze", "tato", "te", "tedy", "ten", "tento", "ti", "tim",
+  "to", "toho", "tohle", "tom", "tomu", "tu", "tuto", "tvuj", "ty", "tyto",
+  "u", "uz", "v", "vam", "vas", "vase", "ve", "vsak", "vse", "vsech",
+  "vsechno", "vsichni", "z", "za", "zda", "zde", "ze",
+]);
+
+export function generateName(prompt: string, maxWords = 4, maxLength = 40): string {
+  const words = prompt
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/-/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+  let name = "";
+  for (const word of words.slice(0, maxWords)) {
+    const candidate = name ? `${name}-${word}` : word;
+    if (candidate.length > maxLength) break;
+    name = candidate;
+  }
+  return name || "task";
+}

package/src/orchestrator.test.ts

@@ -103,7 +103,8 @@ describe("Orchestrator", () => {
       orch.handleMessage("hello");
       await waitForProcessing();
 
-      expect(claude.calls[0].prompt).toBe("hello");
+      expect(claude.calls[0].prompt).toContain('type="user-message"');
+      expect(claude.calls[0].prompt).toContain("<text>hello</text>");
     });
 
     it("prepends file references for user requests", async () => {
@@ -113,7 +114,9 @@ describe("Orchestrator", () => {
       orch.handleMessage("check this", ["/tmp/photo.jpg", "/tmp/doc.pdf"]);
       await waitForProcessing();
 
-      expect(claude.calls[0].prompt).toBe("[File: /tmp/photo.jpg]\n[File: /tmp/doc.pdf]\ncheck this");
+      expect(claude.calls[0].prompt).toContain('<file path="/tmp/photo.jpg" />');
+      expect(claude.calls[0].prompt).toContain('<file path="/tmp/doc.pdf" />');
+      expect(claude.calls[0].prompt).toContain("<text>check this</text>");
     });
 
     it("sends only file references when message is empty", async () => {
@@ -123,7 +126,8 @@ describe("Orchestrator", () => {
       orch.handleMessage("", ["/tmp/photo.jpg"]);
       await waitForProcessing();
 
-      expect(claude.calls[0].prompt).toBe("[File: /tmp/photo.jpg]");
+      expect(claude.calls[0].prompt).toContain('<file path="/tmp/photo.jpg" />');
+      expect(claude.calls[0].prompt).not.toContain("<text>");
     });
 
     it("builds button click prompt", async () => {
@@ -133,7 +137,7 @@ describe("Orchestrator", () => {
       orch.handleButton("Yes");
       await waitForProcessing();
 
-      expect(claude.calls[0].prompt).toBe('[Context: button-click] User tapped "Yes"');
+      expect(claude.calls[0].prompt).toContain('<button>Yes</button>');
     });
   });
 
@@ -338,9 +342,8 @@ describe("Orchestrator", () => {
       expect(callCount).toBe(2);
       const secondCall = claude.calls[1];
       expect(secondCall.method).toBe("forkSession");
-      expect(secondCall.prompt).toContain("[Context: previous task");
-      expect(secondCall.prompt).toContain("moved to background]");
-      expect(secondCall.prompt).toContain("second");
+      expect(secondCall.prompt).toContain("<backgrounded-event");
+      expect(secondCall.prompt).toContain("<text>second</text>");
 
       // Resolve both
       resolve2(queryResult({ action: "send", message: "second done", actionReason: "ok" }, "q2-sid"));
@@ -405,7 +408,7 @@ describe("Orchestrator", () => {
 
       expect(callCount).toBe(2);
       const userCall = claude.calls[1];
-      expect(userCall.prompt).toContain("[Context: previous task");
+      expect(userCall.prompt).toContain("<backgrounded-event");
       expect(userCall.prompt).toContain("follow up");
       expect(responses.map((r) => r.message)).toContain("forked result");
     });
@@ -451,7 +454,7 @@ describe("Orchestrator", () => {
       orch.handleButton("Yes");
       await waitForProcessing();
 
-      expect(claude.calls[0].prompt).toBe('[Context: button-click] User tapped "Yes"');
+      expect(claude.calls[0].prompt).toContain('<button>Yes</button>');
       expect(responses[0].message).toBe("button response");
     });
 
@@ -503,8 +506,8 @@ describe("Orchestrator", () => {
       await waitForProcessing();
 
       expect(claude.calls[0].method).toBe("forkSession");
-      expect(claude.calls[0].prompt).toContain("[Context: background-agent/cron-daily-check]");
-      expect(claude.calls[0].prompt).toContain("[Context: cron/daily-check] Check for updates");
+      expect(claude.calls[0].prompt).toContain('<schedule name="daily-check" />');
+      expect(claude.calls[0].prompt).toContain("<text>Check for updates</text>");
       expect(claude.calls[0].model).toBe("haiku");
     });
 

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";
 
@@ -58,7 +59,6 @@ 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: "button"; label: string };
 
@@ -115,14 +115,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 +190,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" },
       );
@@ -249,13 +261,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 +300,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 +313,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) {
@@ -342,19 +352,56 @@ 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":
-        return `[Context: background-result/${request.name}] ${request.response.message || "[No output]"}`;
+        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 "button":
-        return `[Context: button-click] User tapped "${request.label}"`;
+        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 `bg:${request.name}`;
+      case "button":
+        return `btn:${request.label}`;
     }
   }
 
@@ -376,10 +423,19 @@ 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);
   }
 

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,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

@@ -15,28 +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.
-- previous task "<prompt>" moved to background — a long-running task was demoted. Mention briefly if relevant.
+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, forked 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 command. Use for long-running tasks that shouldn't block.
 
 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. \
-You may see a [Context: previous task "..." moved to background] prefix when this happens.
+The new event will contain a <backgrounded-event> element (see above).
 
-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.
+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). 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";
 		}