macroclaw 0.28.0 → 0.29.0

package/package.json

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

package/src/orchestrator.test.ts

@@ -920,6 +920,154 @@ describe("Orchestrator", () => {
     });
   });
 
+  describe("health checks", () => {
+    it("runs health check after interval and reports finished agent", async () => {
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      const { query: bgQuery } = pendingQuery("bg-sid");
+
+      let callCount = 0;
+      const claude = mockClaude((info: CallInfo): RunningQuery<unknown> => {
+        callCount++;
+        if (callCount === 1) return bgQuery; // background agent spawn
+        if (info.prompt.includes("health-check")) {
+          return resolvedQuery({
+            finished: true,
+            output: { action: "send", message: "task complete", actionReason: "done" },
+          }, "hc-sid");
+        }
+        // Main session processes the background-agent-result
+        return resolvedQuery({ action: "send", message: "relayed", actionReason: "ok" });
+      });
+
+      const { orch } = makeOrchestrator(claude, {
+        healthCheckInterval: 50,
+        healthCheckTimeout: 5000,
+      });
+
+      orch.handleBackgroundCommand("long task");
+      await waitForProcessing(200);
+
+      // Health check should have fired, detected finished, killed original, and pushed result
+      expect(callCount).toBeGreaterThanOrEqual(2);
+      const hcCall = claude.calls.find((c: CallInfo) => c.prompt.includes("health-check"));
+      expect(hcCall).toBeDefined();
+      expect(hcCall!.model).toBe("haiku");
+    });
+
+    it("reports progress and schedules next check when not finished", async () => {
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      const { query: bgQuery } = pendingQuery("bg-sid");
+
+      let hcCount = 0;
+      const claude = mockClaude((info: CallInfo): RunningQuery<unknown> => {
+        if (info.prompt.includes("health-check")) {
+          hcCount++;
+          return resolvedQuery({ finished: false, progress: "still working" }, "hc-sid");
+        }
+        if (info.prompt.includes("background-agent-result")) {
+          return resolvedQuery({ action: "silent", message: "ok", actionReason: "progress" });
+        }
+        return bgQuery; // background agent spawn
+      });
+
+      const { orch } = makeOrchestrator(claude, {
+        healthCheckInterval: 50,
+        healthCheckTimeout: 5000,
+      });
+
+      orch.handleBackgroundCommand("long task");
+      // Wait for two health check cycles
+      await waitForProcessing(250);
+
+      expect(hcCount).toBeGreaterThanOrEqual(2);
+    });
+
+    it("kills unresponsive agent on health check timeout", async () => {
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      const { query: bgQuery } = pendingQuery("bg-sid");
+
+      const claude = mockClaude((info: CallInfo): RunningQuery<unknown> => {
+        if (info.prompt.includes("health-check")) {
+          // Never resolves — simulates unresponsive agent
+          return { sessionId: "hc-sid", startedAt: new Date(), result: new Promise(() => {}), kill: mock(async () => {}) };
+        }
+        return bgQuery;
+      });
+
+      const { orch, responses } = makeOrchestrator(claude, {
+        healthCheckInterval: 30,
+        healthCheckTimeout: 60,
+      });
+
+      orch.handleBackgroundCommand("stuck task");
+      await waitForProcessing(200);
+
+      const killMsg = responses.find((r) => r.message.includes("unresponsive"));
+      expect(killMsg).toBeDefined();
+    });
+
+    it("does not run health checks when interval is 0", async () => {
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      const { query: bgQuery } = pendingQuery("bg-sid");
+
+      const claude = mockClaude((): RunningQuery<unknown> => bgQuery);
+      const { orch } = makeOrchestrator(claude, { healthCheckInterval: 0 });
+
+      orch.handleBackgroundCommand("some task");
+      await waitForProcessing(100);
+
+      // Only the spawn call, no health check fork
+      expect(claude.calls).toHaveLength(1);
+    });
+
+    it("clears health check timer when session is killed", async () => {
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      const { query: bgQuery } = pendingQuery("bg-sid");
+
+      let hcCount = 0;
+      const claude = mockClaude((info: CallInfo): RunningQuery<unknown> => {
+        if (info.prompt.includes("health-check")) hcCount++;
+        return bgQuery;
+      });
+
+      const { orch } = makeOrchestrator(claude, { healthCheckInterval: 100 });
+
+      orch.handleBackgroundCommand("killable task");
+      await waitForProcessing();
+
+      // Get the session ID and kill it before health check fires
+      orch.handleKill("bg-sid");
+      await waitForProcessing(200);
+
+      expect(hcCount).toBe(0);
+    });
+
+    it("stops health check if session completes organically before timer", async () => {
+      saveSessions({ mainSessionId: "test-session" }, tmpSettingsDir);
+      const { query: bgQuery, resolve: resolveBg } = pendingQuery("bg-sid");
+
+      let hcCount = 0;
+      let callCount = 0;
+      const claude = mockClaude((info: CallInfo): RunningQuery<unknown> => {
+        callCount++;
+        if (info.prompt.includes("health-check")) { hcCount++; return pendingQuery().query; }
+        if (callCount === 1) return bgQuery;
+        return resolvedQuery({ action: "send", message: "processed", actionReason: "ok" });
+      });
+
+      const { orch } = makeOrchestrator(claude, { healthCheckInterval: 200 });
+
+      orch.handleBackgroundCommand("fast task");
+      await waitForProcessing();
+
+      // Complete before health check fires
+      resolveBg(queryResult({ action: "send", message: "done", actionReason: "done" }));
+      await waitForProcessing(350);
+
+      expect(hcCount).toBe(0);
+    });
+  });
+
   describe("onResponse error handling", () => {
     it("logs error and does not throw when onResponse callback fails", async () => {
       const claude = mockClaude({ action: "send", message: "hello", actionReason: "ok" });

package/src/orchestrator.ts

@@ -20,6 +20,8 @@ const log = createLogger("orchestrator");
 // --- Constants ---
 
 const WAIT_THRESHOLD = 60_000;
+const HEALTH_CHECK_INTERVAL_MS = 5 * 60 * 1000;
+const HEALTH_CHECK_TIMEOUT_MS = 120 * 1000;
 
 // --- Response schema ---
 
@@ -40,7 +42,14 @@ const agentOutputSchema = z.object({
 
 type AgentOutput = z.infer<typeof agentOutputSchema>;
 
+const healthCheckSchema = z.object({
+  finished: z.boolean().describe("True if the task is complete, false if still working"),
+  output: agentOutputSchema.optional().describe("Full output when finished=true"),
+  progress: z.string().optional().describe("One-sentence status when finished=false"),
+});
+
 const responseResultType = { type: "object" as const, schema: agentOutputSchema };
+const healthCheckResultType = { type: "object" as const, schema: healthCheckSchema };
 
 const textResultType = { type: "text" } as const;
 
@@ -60,6 +69,7 @@ export interface OrchestratorResponse {
 type OrchestratorRequest =
   | { type: "user"; message: string; files?: string[] }
   | { type: "background-agent-result"; name: string; response: AgentOutput }
+  | { type: "background-agent-progress"; name: string; progress: string }
   | { type: "button"; label: string };
 
 function escapeHtml(text: string): string {
@@ -74,6 +84,7 @@ interface SessionInfo {
   model?: string;
   query: RunningQuery<AgentOutput>;
   lastMessageAt: Date;
+  healthCheckTimer?: Timer;
 }
 
 export interface OrchestratorConfig {
@@ -84,12 +95,18 @@ export interface OrchestratorConfig {
   claude?: Claude;
   /** How long to wait for a running main session before demoting it (ms). Default: 60000 */
   waitThreshold?: number;
+  /** Interval between background agent health checks (ms). Default: 300000. Set to 0 to disable. */
+  healthCheckInterval?: number;
+  /** Timeout for health check fork responses (ms). Default: 120000 */
+  healthCheckTimeout?: number;
 }
 
 export class Orchestrator {
   #config: Omit<OrchestratorConfig , 'claude'>;
   #claude: Claude;
   #waitThreshold: number;
+  #healthCheckInterval: number;
+  #healthCheckTimeout: number;
 
   #mainSessionId: string | undefined;
   #runningSessions = new Map<string, SessionInfo>();
@@ -99,6 +116,8 @@ export class Orchestrator {
     this.#config = config;
     this.#claude = config.claude ?? new Claude({ workspace: config.workspace, systemPrompt: SYSTEM_PROMPT });
     this.#waitThreshold = config.waitThreshold ?? WAIT_THRESHOLD;
+    this.#healthCheckInterval = config.healthCheckInterval ?? HEALTH_CHECK_INTERVAL_MS;
+    this.#healthCheckTimeout = config.healthCheckTimeout ?? HEALTH_CHECK_TIMEOUT_MS;
     this.#queue = new Queue<OrchestratorRequest>();
     this.#queue.setHandler((request) => this.#handleRequest(request));
 
@@ -217,7 +236,7 @@ export class Orchestrator {
       return;
     }
 
-    this.#runningSessions.delete(sessionId);
+    this.#clearSession(sessionId);
 
     try {
       await session.query.kill();
@@ -330,7 +349,7 @@ export class Orchestrator {
           await this.#deliverResponse(response);
           return;
         }
-        this.#runningSessions.delete(sid);
+        this.#clearSession(sid);
 
         if (sid === this.#mainSessionId) {
           log.debug({ name, sessionId: sid }, "Main query finished, delivering directly");
@@ -344,7 +363,7 @@ export class Orchestrator {
         if (!this.#runningSessions.has(sid)) {
           log.error({ name, sessionId: sid, err }, "Failed session not in runningSessions — delivering error");
         } else {
-          this.#runningSessions.delete(sid);
+          this.#clearSession(sid);
           log.error({ name, sessionId: sid, err }, "Main query failed");
         }
         await this.#deliverResponse(this.#errorResponse(err));
@@ -380,6 +399,17 @@ export class Orchestrator {
           instructions: "Forward this result to the user (action=\"send\"). Summarize or add context from the conversation as appropriate.",
         };
         break;
+      case "background-agent-progress":
+        input = {
+          name,
+          type: "background-agent-progress",
+          session: "main",
+          originalEvent: request.name,
+          progress: request.progress,
+          instructions: "This is an interim progress update, not a final result. Do not report to the user unless it contains exceptionally important information.",
+          backgroundedEvent,
+        };
+        break;
       case "button":
         input = {
           name,
@@ -400,6 +430,8 @@ export class Orchestrator {
         return request.message;
       case "background-agent-result":
         return `bg:${request.name}`;
+      case "background-agent-progress":
+        return `progress:${request.name}`;
       case "button":
         return `btn:${request.label}`;
     }
@@ -441,23 +473,108 @@ export class Orchestrator {
 
   #registerBackground(name: string, prompt: string, model: string | undefined, query: RunningQuery<AgentOutput>) {
     const sid = query.sessionId;
-    this.#runningSessions.set(sid, { name, prompt, model, query, lastMessageAt: new Date() });
+    const info: SessionInfo = { name, prompt, model, query, lastMessageAt: new Date() };
+    this.#runningSessions.set(sid, info);
 
     log.debug({ name, sessionId: sid }, "Background session registered");
 
+    this.#scheduleHealthCheck(sid);
+
     query.result.then(
       ({ value: response }) => {
         if (!this.#runningSessions.has(sid)) return;
-        this.#runningSessions.delete(sid);
+        this.#clearSession(sid);
         log.debug({ name, message: response.message }, "Background session finished");
         this.#queue.push({ type: "background-agent-result", name, response });
       },
       (err) => {
         if (!this.#runningSessions.has(sid)) return;
-        this.#runningSessions.delete(sid);
+        this.#clearSession(sid);
         log.error({ name, err }, "Background session failed");
         this.#queue.push({ type: "background-agent-result", name, response: { action: "send", message: `[Error] ${err}`, actionReason: "bg-failed" } });
       },
     );
   }
+
+  // --- Session cleanup ---
+
+  #clearSession(sessionId: string) {
+    const info = this.#runningSessions.get(sessionId);
+    if (info?.healthCheckTimer) clearTimeout(info.healthCheckTimer);
+    this.#runningSessions.delete(sessionId);
+  }
+
+  // --- Health checks ---
+
+  #scheduleHealthCheck(sessionId: string) {
+    if (this.#healthCheckInterval <= 0) return;
+
+    const info = this.#runningSessions.get(sessionId);
+    if (!info) return;
+
+    info.healthCheckTimer = setTimeout(() => {
+      this.#runHealthCheck(sessionId);
+    }, this.#healthCheckInterval);
+  }
+
+  async #runHealthCheck(sessionId: string): Promise<void> {
+    const info = this.#runningSessions.get(sessionId);
+    if (!info) return;
+
+    log.debug({ name: info.name, sessionId }, "Running health check");
+
+    const prompt = buildEvent({
+      name: `health-check-${info.name}`,
+      type: "health-check",
+      session: "background",
+      targetEvent: info.name,
+      instructions: "Report your current status. If your task is complete, set finished=true and provide the full output. If still working, set finished=false and describe current progress in one sentence.",
+    });
+
+    let query: RunningQuery<z.infer<typeof healthCheckSchema>>;
+    try {
+      query = this.#claude.forkSession(sessionId, prompt, healthCheckResultType, { model: "haiku" });
+    } catch (err) {
+      log.error({ name: info.name, sessionId, err }, "Health check fork failed");
+      this.#scheduleHealthCheck(sessionId);
+      return;
+    }
+
+    const result = await Promise.race([
+      query.result.then((r) => r.value),
+      new Promise<"timeout">((r) => setTimeout(() => r("timeout"), this.#healthCheckTimeout)),
+    ]);
+
+    // Session may have completed/been killed while health check was running
+    if (!this.#runningSessions.has(sessionId)) return;
+
+    if (result === "timeout") {
+      log.warn({ name: info.name, sessionId }, "Health check timed out, killing session");
+      try { await query.kill(); } catch { /* ignore */ }
+      this.#clearSession(sessionId);
+      try { await info.query.kill(); } catch { /* ignore */ }
+      this.#callOnResponse({ message: `Agent <b>${escapeHtml(info.name)}</b> appears unresponsive, killed it.` });
+      return;
+    }
+
+    if (result.finished) {
+      log.info({ name: info.name, sessionId }, "Health check: agent reports finished");
+      this.#clearSession(sessionId);
+      try { await info.query.kill(); } catch { /* ignore */ }
+      const response = result.output ?? { action: "send" as const, message: "[Agent finished but returned no output]", actionReason: "health-check-finished" };
+      this.#queue.push({ type: "background-agent-result", name: info.name, response });
+      return;
+    }
+
+    log.debug({ name: info.name, progress: result.progress }, "Health check: still running");
+    if (result.progress) {
+      this.#queue.push({
+        type: "background-agent-progress",
+        name: info.name,
+        progress: result.progress,
+      });
+    }
+
+    this.#scheduleHealthCheck(sessionId);
+  }
 }

package/src/prompts.test.ts

@@ -231,6 +231,20 @@ describe("buildEvent", () => {
     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",

package/src/prompts.ts

@@ -23,7 +23,9 @@ Event format: every incoming message is wrapped in an <event> XML block. Attribu
   - 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.
+  - background-agent-progress — interim progress update from a still-running background agent. Contains <original-event name="..." /> and a <progress> element. This is NOT a final result. Do not report to the user unless it contains exceptionally important information (errors, blockers, urgent findings). Keep this context in mind — if the user later asks about progress of a background task, use the latest progress update to answer.
   - 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.
+  - health-check — automated status check on a background agent. Contains <target-event name="..." />. Report whether the task is complete or still in progress.
 - session — "main" (primary conversation) or "background" (background agent).
 
 Backgrounded events: when a new message arrives while a previous task is still running, \
@@ -40,6 +42,7 @@ Inner elements:
 - <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.
+- <progress> — interim status from a still-running background agent.
 - <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.
 
@@ -76,7 +79,9 @@ export type EventType =
   | "schedule-trigger"
   | "background-agent-start"
   | "background-agent-result"
-  | "peek";
+  | "background-agent-progress"
+  | "peek"
+  | "health-check";
 
 export interface EventInput {
   name: string;
@@ -90,6 +95,7 @@ export interface EventInput {
   originalEvent?: string;
   targetEvent?: string;
   instructions?: string;
+  progress?: string;
   result?: { text: string; files?: string[] };
 }
 
@@ -121,6 +127,11 @@ export function buildEvent(input: EventInput): string {
     lines.push(`<target-event name="${escapeXml(input.targetEvent)}" />`);
   }
 
+  // Progress (for background-agent-progress)
+  if (input.progress) {
+    lines.push(`<progress>${escapeXml(input.progress)}</progress>`);
+  }
+
   // Result block (for background-agent-result)
   if (input.result) {
     lines.push("<result>");