macroclaw 0.31.0 → 0.33.0

package/src/orchestrator.ts

@@ -1,15 +1,26 @@
 import { z } from "zod/v4";
 import {
   Claude,
+  type ClaudeProcess,
   QueryParseError,
   QueryProcessError,
+  type QueryResult,
   QueryValidationError,
-  type RunningQuery
 } from "./claude";
 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";
 
@@ -82,7 +93,8 @@ interface SessionInfo {
   name: string;
   prompt: string;
   model?: string;
-  query: RunningQuery<AgentOutput>;
+  process: ClaudeProcess<AgentOutput>;
+  pendingResult: Promise<QueryResult<AgentOutput>>;
   lastMessageAt: Date;
   healthCheckTimer?: Timer;
 }
@@ -109,6 +121,7 @@ export class Orchestrator {
   #healthCheckTimeout: number;
 
   #mainSessionId: string | undefined;
+  #mainProcess: ClaudeProcess<AgentOutput> | null = null;
   #runningSessions = new Map<string, SessionInfo>();
   #queue: Queue<OrchestratorRequest>;
 
@@ -136,13 +149,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);
   }
 
@@ -159,14 +170,14 @@ export class Orchestrator {
       return;
     }
     const lines = sessions.map(([sid, s]) => {
-      const elapsed = Math.round((Date.now() - s.query.startedAt.getTime()) / 1000);
+      const elapsed = Math.round((Date.now() - s.process.startedAt.getTime()) / 1000);
       const isMain = sid === this.#mainSessionId;
       return isMain
         ? `▶ ${escapeHtml(s.name)} (${elapsed}s) [main]`
         : `- ${escapeHtml(s.name)} (${elapsed}s)`;
     });
     const buttons: ButtonSpec[] = sessions.map(([sid, s]) => {
-      const elapsed = Math.round((Date.now() - s.query.startedAt.getTime()) / 1000);
+      const elapsed = Math.round((Date.now() - s.process.startedAt.getTime()) / 1000);
       const text = `${s.name} (${elapsed}s)`.slice(0, 27);
       return { text, data: `detail:${sid}` };
     });
@@ -181,7 +192,7 @@ export class Orchestrator {
       return;
     }
 
-    const elapsed = Math.round((Date.now() - session.query.startedAt.getTime()) / 1000);
+    const elapsed = Math.round((Date.now() - session.process.startedAt.getTime()) / 1000);
     const truncatedPrompt = session.prompt.length > 300 ? `${session.prompt.slice(0, 300)}…` : session.prompt;
     const isMain = sessionId === this.#mainSessionId;
     const lines = [
@@ -209,20 +220,18 @@ 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 query = this.#claude.forkSession(
+      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 peekProcess = this.#claude.forkSession(
         sessionId,
-        prompt,
         textResultType,
         { model: "haiku" },
       );
-      const { value } = await query.result;
+      const { value } = await peekProcess.send(prompt);
+      peekProcess.kill().catch(() => {});
       this.#callOnResponse({ message: `<b>[${escapeHtml(session.name)}]</b> ${value || "[No output]"}` });
     } catch (err) {
       this.#callOnResponse({ message: `Couldn't peek at ${escapeHtml(session.name)}: ${err}` });
@@ -239,7 +248,7 @@ export class Orchestrator {
     this.#clearSession(sessionId);
 
     try {
-      await session.query.kill();
+      await session.process.kill();
     } catch (err) {
       log.error({ err, name: session.name }, "Kill failed");
     }
@@ -247,102 +256,127 @@ export class Orchestrator {
     this.#callOnResponse({ message: `Killed <b>${escapeHtml(session.name)}</b>.` });
   }
 
+  async handleClear(): Promise<void> {
+    const sid = this.#mainProcess?.sessionId;
+    if (sid) {
+      this.#clearSession(sid);
+    }
+    if (this.#mainProcess) {
+      try {
+        await this.#mainProcess.kill();
+      } catch (err) {
+        log.error({ err }, "Failed to kill main process during clear");
+      }
+      this.#mainProcess = null;
+    }
+    this.#mainSessionId = undefined;
+    saveSessions({}, this.#config.settingsDir);
+    log.info("Session cleared");
+    this.#callOnResponse({ message: "Session cleared." });
+  }
+
+  /** Tear down all sessions and the main process. Used in tests. */
+  async dispose(): Promise<void> {
+    for (const sid of [...this.#runningSessions.keys()]) {
+      this.#clearSession(sid);
+    }
+    if (this.#mainProcess) {
+      await this.#mainProcess.kill().catch(() => {});
+      this.#mainProcess = null;
+    }
+  }
+
+  // --- Main process lifecycle ---
+
+  #ensureMainProcess(): ClaudeProcess<AgentOutput> {
+    if (this.#mainProcess && this.#mainProcess.state !== "dead") {
+      return this.#mainProcess;
+    }
+
+    const opts = { model: this.#config.model };
+    this.#mainProcess = this.#mainSessionId
+      ? this.#claude.resumeSession(this.#mainSessionId, responseResultType, opts)
+      : this.#claude.newSession(responseResultType, opts);
+
+    if (this.#mainProcess.sessionId !== this.#mainSessionId) {
+      this.#mainSessionId = this.#mainProcess.sessionId;
+      saveSessions({ mainSessionId: this.#mainSessionId }, this.#config.settingsDir);
+    }
+
+    log.info({ sessionId: this.#mainSessionId }, "Main process created");
+    return this.#mainProcess;
+  }
 
   // --- Internal queue handler ---
 
   async #handleRequest(request: OrchestratorRequest): Promise<void> {
     log.debug({ type: request.type }, "Incoming request");
 
-    const mainInfo = this.#mainSessionId ? this.#runningSessions.get(this.#mainSessionId) : undefined;
     let movedToBackground: string | undefined;
-
-    if (mainInfo) {
-      const elapsed = Date.now() - mainInfo.lastMessageAt.getTime();
-      if (elapsed >= this.#waitThreshold) {
-        // Main has been running too long — move to background immediately
-        log.info({ name: mainInfo.name, sessionId: mainInfo.query.sessionId }, "Moving main session to background (exceeded threshold)");
-        movedToBackground = mainInfo.prompt;
-      } else {
-        // Main started recently — wait for it to finish or threshold
-        const remaining = this.#waitThreshold - elapsed;
-        const finished = await Promise.race([
-          mainInfo.query.result.then(() => true as const, () => true as const),
-          new Promise<false>((r) => setTimeout(() => r(false), remaining)),
-        ]);
-
-        if (!finished) {
-          log.info({ name: mainInfo.name, sessionId: mainInfo.query.sessionId }, "Moving main session to background (wait timed out)");
+    let backgroundedName: string | undefined;
+    const currentMain = this.#mainProcess;
+
+    if (currentMain?.state === "busy") {
+      const mainInfo = this.#runningSessions.get(currentMain.sessionId);
+      if (mainInfo) {
+        const elapsed = Date.now() - mainInfo.lastMessageAt.getTime();
+        if (elapsed >= this.#waitThreshold) {
           movedToBackground = mainInfo.prompt;
+          backgroundedName = mainInfo.name;
+        } else {
+          const remaining = this.#waitThreshold - elapsed;
+          const finished = await Promise.race([
+            mainInfo.pendingResult.then(() => true as const, () => true as const),
+            new Promise<false>((r) => setTimeout(() => r(false), remaining)),
+          ]);
+
+          if (!finished) {
+            movedToBackground = mainInfo.prompt;
+            backgroundedName = mainInfo.name;
+          }
         }
-        // If finished: completion handler already delivered the result and removed from map.
       }
     }
 
+    if (movedToBackground && currentMain) {
+      log.info({ name: backgroundedName, sessionId: currentMain.sessionId }, "Moving main session to background");
+      this.#mainProcess = this.#claude.forkSession(
+        this.#mainSessionId ?? currentMain.sessionId,
+        responseResultType,
+        { model: this.#config.model },
+      );
+      this.#mainSessionId = this.#mainProcess.sessionId;
+      saveSessions({ mainSessionId: this.#mainSessionId }, this.#config.settingsDir);
+    }
+
     await writeHistoryPrompt(request);
 
     const label = Orchestrator.#requestLabel(request);
     const name = generateName(label);
-    const backgroundedName = movedToBackground ? mainInfo?.name : undefined;
     const formatted = this.#formatPrompt(request, name, backgroundedName);
 
-    this.#startMainQuery(name, label, formatted, this.#config.model);
+    this.#sendToMain(name, label, formatted);
   }
 
-  // --- Response delivery ---
+  // --- Main session send ---
 
-  async #deliverResponse(response: AgentOutput): Promise<void> {
-    await writeHistoryResult(response);
-    if (response.action === "send") {
-      this.#callOnResponse({
-        message: response.message || "[No output]",
-        files: response.files,
-        buttons: response.buttons,
-      });
-    } else {
-      log.debug("Silent response");
-    }
+  #sendToMain(name: string, displayPrompt: string, formatted: string): void {
+    const process = this.#ensureMainProcess();
+    const sid = process.sessionId;
 
-    if (response.backgroundAgents?.length) {
-      for (const agent of response.backgroundAgents) {
-        const agentModel = agent.model ?? this.#config.model;
-        this.#spawnBackground(agent.name, agent.prompt, agentModel);
-        this.#callOnResponse({ message: `Background agent "${escapeHtml(agent.name)}" started.` });
-      }
-    }
-  }
-
-  #callOnResponse(response: OrchestratorResponse): void {
-    this.#config.onResponse(response).catch((err) => {
-      log.error({ err }, "onResponse callback failed");
+    const pendingResult = process.send(formatted);
+    this.#runningSessions.set(sid, {
+      name,
+      prompt: displayPrompt,
+      model: this.#config.model,
+      process,
+      pendingResult,
+      lastMessageAt: new Date(),
     });
-  }
-
-  // --- Main session query ---
-
-  #startMainQuery(name: string, displayPrompt: string, formatted: string, model: string | undefined): void {
-    const opts = { model };
-    let query: RunningQuery<AgentOutput>;
-
-    if (this.#mainSessionId && this.#runningSessions.has(this.#mainSessionId)) {
-      query = this.#claude.forkSession(this.#mainSessionId, formatted, responseResultType, opts);
-    } else if (this.#mainSessionId) {
-      query = this.#claude.resumeSession(this.#mainSessionId, formatted, responseResultType, opts);
-    } else {
-      query = this.#claude.newSession(formatted, responseResultType, opts);
-    }
 
-    const sid = query.sessionId;
-    this.#runningSessions.set(sid, { name, prompt: displayPrompt, model, query, lastMessageAt: new Date() });
+    log.debug({ name, sessionId: sid }, "Main query sent");
 
-    if (sid !== this.#mainSessionId) {
-      log.info({ oldSessionId: this.#mainSessionId, newSessionId: sid }, "Session updated");
-      this.#mainSessionId = sid;
-      saveSessions({ mainSessionId: sid }, this.#config.settingsDir);
-    }
-
-    log.debug({ name, sessionId: sid }, "Main query started");
-
-    query.result.then(
+    pendingResult.then(
       async ({ value: response }) => {
         if (!this.#runningSessions.has(sid)) {
           log.error({ name, sessionId: sid }, "Completed session not in runningSessions — delivering anyway");
@@ -351,11 +385,12 @@ export class Orchestrator {
         }
         this.#clearSession(sid);
 
-        if (sid === this.#mainSessionId) {
+        if (process === this.#mainProcess) {
           log.debug({ name, sessionId: sid }, "Main query finished, delivering directly");
           await this.#deliverResponse(response);
         } else {
           log.debug({ name, sessionId: sid }, "Non-main query finished, feeding to main session");
+          process.kill().catch(() => {});
           this.#queue.push({ type: "background-agent-result", name, response });
         }
       },
@@ -371,57 +406,58 @@ export class Orchestrator {
     );
   }
 
-  #formatPrompt(request: OrchestratorRequest, name: string, backgroundedEvent?: string): string {
-    let input: EventInput;
+  // --- Response delivery ---
+
+  async #deliverResponse(response: AgentOutput): Promise<void> {
+    await writeHistoryResult(response);
+    if (response.action === "send") {
+      this.#callOnResponse({
+        message: response.message || "[No output]",
+        files: response.files,
+        buttons: response.buttons,
+      });
+    } else {
+      log.debug("Silent response");
+    }
+
+    if (response.backgroundAgents?.length) {
+      for (const agent of response.backgroundAgents) {
+        const agentModel = agent.model ?? this.#config.model;
+        this.#spawnBackground(agent.name, agent.prompt, agentModel);
+        this.#callOnResponse({ message: `Background agent "${escapeHtml(agent.name)}" started.` });
+      }
+    }
+  }
 
+  #callOnResponse(response: OrchestratorResponse): void {
+    this.#config.onResponse(response).catch((err) => {
+      log.error({ err }, "onResponse callback failed");
+    });
+  }
+
+  #formatPrompt(request: OrchestratorRequest, name: string, backgroundedEvent?: string): string {
     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,41 +491,37 @@ 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);
   }
 
   #spawnBackgroundRaw(name: string, prompt: string, formatted: string, model: string | undefined) {
-    const query = this.#mainSessionId
-      ? this.#claude.forkSession(this.#mainSessionId, formatted, responseResultType, { model })
-      : this.#claude.newSession(formatted, responseResultType, { model });
-    this.#registerBackground(name, prompt, model, query);
-  }
+    const process = this.#mainSessionId
+      ? this.#claude.forkSession(this.#mainSessionId, responseResultType, { model })
+      : this.#claude.newSession(responseResultType, { model });
+
+    const sid = process.sessionId;
+    const pendingResult = process.send(formatted);
 
-  #registerBackground(name: string, prompt: string, model: string | undefined, query: RunningQuery<AgentOutput>) {
-    const sid = query.sessionId;
-    const info: SessionInfo = { name, prompt, model, query, lastMessageAt: new Date() };
+    const info: SessionInfo = { name, prompt, model, process, pendingResult, lastMessageAt: new Date() };
     this.#runningSessions.set(sid, info);
 
     log.debug({ name, sessionId: sid }, "Background session registered");
 
     this.#scheduleHealthCheck(sid);
 
-    query.result.then(
+    pendingResult.then(
       ({ value: response }) => {
         if (!this.#runningSessions.has(sid)) return;
         this.#clearSession(sid);
+        process.kill().catch(() => {});
         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.#clearSession(sid);
+        process.kill().catch(() => {});
         log.error({ name, err }, "Background session failed");
         this.#queue.push({ type: "background-agent-result", name, response: { action: "send", message: `[Error] ${err}`, actionReason: "bg-failed" } });
       },
@@ -523,17 +555,15 @@ 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>>;
+    let hcProcess: ClaudeProcess<z.infer<typeof healthCheckSchema>>;
     try {
-      query = this.#claude.forkSession(sessionId, prompt, healthCheckResultType, { model: "haiku" });
+      hcProcess = this.#claude.forkSession(sessionId, healthCheckResultType, { model: "haiku" });
     } catch (err) {
       log.error({ name: info.name, sessionId, err }, "Health check fork failed");
       this.#scheduleHealthCheck(sessionId);
@@ -541,18 +571,20 @@ export class Orchestrator {
     }
 
     const result = await Promise.race([
-      query.result.then((r) => r.value),
+      hcProcess.send(prompt).then((r) => r.value),
       new Promise<"timeout">((r) => setTimeout(() => r("timeout"), this.#healthCheckTimeout)),
     ]);
 
+    // Always kill health check process
+    hcProcess.kill().catch(() => {});
+
     // 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 */ }
+      try { await info.process.kill(); } catch { /* ignore */ }
       this.#callOnResponse({ message: `Agent <b>${escapeHtml(info.name)}</b> appears unresponsive, killed it.` });
       return;
     }
@@ -560,7 +592,7 @@ export class Orchestrator {
     if (result.finished) {
       log.info({ name: info.name, sessionId }, "Health check: agent reports finished");
       this.#clearSession(sessionId);
-      try { await info.query.kill(); } catch { /* ignore */ }
+      try { await info.process.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;