macroclaw 0.26.0 → 0.27.0

package/src/orchestrator.ts

@@ -3,13 +3,12 @@ import {
   Claude,
   QueryParseError,
   QueryProcessError,
-  type QueryResult,
   QueryValidationError,
   type RunningQuery
 } from "./claude";
 import { writeHistoryPrompt, writeHistoryResult } from "./history";
 import { createLogger } from "./logger";
-import { CRON_TIMEOUT, MAIN_TIMEOUT, SYSTEM_PROMPT } from "./prompts";
+import { SYSTEM_PROMPT } from "./prompts";
 import { Queue } from "./queue";
 import { loadSessions, saveSessions } from "./sessions";
 
@@ -17,6 +16,10 @@ type ButtonSpec = string | { text: string; data: string };
 
 const log = createLogger("orchestrator");
 
+// --- Constants ---
+
+const WAIT_THRESHOLD = 60_000;
+
 // --- Response schema ---
 
 const backgroundAgentSchema = z.object({
@@ -56,20 +59,21 @@ 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; sessionId?: string }
+  | { type: "background-agent-result"; name: string; response: AgentOutput }
   | { type: "button"; label: string };
 
 function escapeHtml(text: string): string {
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
-// --- Background tracking ---
+// --- Session tracking ---
 
-interface BackgroundInfo {
+interface SessionInfo {
   name: string;
   prompt: string;
   model?: string;
   query: RunningQuery<AgentOutput>;
+  lastMessageAt: Date;
 }
 
 export interface OrchestratorConfig {
@@ -78,19 +82,23 @@ export interface OrchestratorConfig {
   settingsDir?: string;
   onResponse: (response: OrchestratorResponse) => Promise<void>;
   claude?: Claude;
+  /** How long to wait for a running main session before demoting it (ms). Default: 60000 */
+  waitThreshold?: number;
 }
 
 export class Orchestrator {
   #config: Omit<OrchestratorConfig , 'claude'>;
   #claude: Claude;
+  #waitThreshold: number;
 
   #mainSessionId: string | undefined;
-  #backgroundAgents = new Map<string, BackgroundInfo>();
+  #runningSessions = new Map<string, SessionInfo>();
   #queue: Queue<OrchestratorRequest>;
 
   constructor(config: OrchestratorConfig) {
     this.#config = config;
     this.#claude = config.claude ?? new Claude({ workspace: config.workspace, systemPrompt: SYSTEM_PROMPT });
+    this.#waitThreshold = config.waitThreshold ?? WAIT_THRESHOLD;
     this.#queue = new Queue<OrchestratorRequest>();
     this.#queue.setHandler((request) => this.#handleRequest(request));
 
@@ -108,7 +116,9 @@ export class Orchestrator {
   }
 
   handleCron(name: string, prompt: string, model?: string): void {
-    this.#queue.push({ type: "cron", name, prompt, model });
+    const cronName = `cron-${name}`;
+    const cronPrompt = `[Context: cron/${name}] ${prompt}`;
+    this.#spawnBackground(cronName, cronPrompt, model ?? this.#config.model);
   }
 
   handleBackgroundCommand(prompt: string): void {
@@ -117,38 +127,42 @@ export class Orchestrator {
     this.#callOnResponse({ message: `Background agent "${escapeHtml(name)}" started.` });
   }
 
-  handleBackgroundList(): void {
-    const agents = [...this.#backgroundAgents.values()];
-    if (agents.length === 0) {
-      this.#callOnResponse({ message: "No background agents running." });
+  handleSessions(): void {
+    const sessions = [...this.#runningSessions.entries()];
+    if (sessions.length === 0) {
+      this.#callOnResponse({ message: "No running sessions." });
       return;
     }
-    const lines = agents.map((a) => {
-      const elapsed = Math.round((Date.now() - a.query.startedAt.getTime()) / 1000);
-      return `- ${escapeHtml(a.name)} (${elapsed}s)`;
+    const lines = sessions.map(([sid, s]) => {
+      const elapsed = Math.round((Date.now() - s.query.startedAt.getTime()) / 1000);
+      const isMain = sid === this.#mainSessionId;
+      return isMain
+        ? `▶ ${escapeHtml(s.name)} (${elapsed}s) [main]`
+        : `- ${escapeHtml(s.name)} (${elapsed}s)`;
     });
-    const buttons: ButtonSpec[] = agents.map((a) => {
-      const elapsed = Math.round((Date.now() - a.query.startedAt.getTime()) / 1000);
-      const text = `${a.name} (${elapsed}s)`.slice(0, 27);
-      return { text, data: `detail:${a.query.sessionId}` };
+    const buttons: ButtonSpec[] = sessions.map(([sid, s]) => {
+      const elapsed = Math.round((Date.now() - s.query.startedAt.getTime()) / 1000);
+      const text = `${s.name} (${elapsed}s)`.slice(0, 27);
+      return { text, data: `detail:${sid}` };
     });
-    buttons.push({text: "Dismiss", data: "_dismiss"});
+    buttons.push({ text: "Dismiss", data: "_dismiss" });
     this.#callOnResponse({ message: lines.join("\n"), buttons });
   }
 
   handleDetail(sessionId: string): void {
-    const agent = this.#backgroundAgents.get(sessionId);
-    if (!agent) {
-      this.#callOnResponse({ message: "Agent not found or already finished." });
+    const session = this.#runningSessions.get(sessionId);
+    if (!session) {
+      this.#callOnResponse({ message: "Session not found or already finished." });
       return;
     }
 
-    const elapsed = Math.round((Date.now() - agent.query.startedAt.getTime()) / 1000);
-    const truncatedPrompt = agent.prompt.length > 300 ? `${agent.prompt.slice(0, 300)}…` : agent.prompt;
+    const elapsed = Math.round((Date.now() - session.query.startedAt.getTime()) / 1000);
+    const truncatedPrompt = session.prompt.length > 300 ? `${session.prompt.slice(0, 300)}…` : session.prompt;
+    const isMain = sessionId === this.#mainSessionId;
     const lines = [
-      `<b>${escapeHtml(agent.name)}</b>`,
+      `<b>${escapeHtml(session.name)}</b>${isMain ? " [main]" : ""}`,
       `Prompt: ${escapeHtml(truncatedPrompt)}`,
-      `Model: ${agent.model ?? "default"}`,
+      `Model: ${session.model ?? "default"}`,
       `Elapsed: ${elapsed}s`,
       "Status: running",
     ];
@@ -161,16 +175,16 @@ export class Orchestrator {
   }
 
   async handlePeek(sessionId: string): Promise<void> {
-    const agent = this.#backgroundAgents.get(sessionId);
-    if (!agent) {
-      this.#callOnResponse({ message: "Agent not found or already finished." });
+    const session = this.#runningSessions.get(sessionId);
+    if (!session) {
+      this.#callOnResponse({ message: "Session not found or already finished." });
       return;
     }
 
-    this.#callOnResponse({ message: `Peeking at <b>${escapeHtml(agent.name)}</b>...` });
+    this.#callOnResponse({ message: `Peeking at <b>${escapeHtml(session.name)}</b>...` });
 
     try {
-      const startedAt = agent.query.startedAt.toISOString();
+      const startedAt = session.query.startedAt.toISOString();
       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.`,
@@ -178,65 +192,76 @@ export class Orchestrator {
         { model: "haiku" },
       );
       const { value } = await query.result;
-      this.#callOnResponse({ message: `<b>[${escapeHtml(agent.name)}]</b> ${value || "[No output]"}` });
+      this.#callOnResponse({ message: `<b>[${escapeHtml(session.name)}]</b> ${value || "[No output]"}` });
     } catch (err) {
-      this.#callOnResponse({ message: `Couldn't peek at ${escapeHtml(agent.name)}: ${err}` });
+      this.#callOnResponse({ message: `Couldn't peek at ${escapeHtml(session.name)}: ${err}` });
     }
   }
 
   async handleKill(sessionId: string): Promise<void> {
-    const agent = this.#backgroundAgents.get(sessionId);
-    if (!agent) {
-      this.#callOnResponse({ message: "Agent not found or already finished." });
+    const session = this.#runningSessions.get(sessionId);
+    if (!session) {
+      this.#callOnResponse({ message: "Session not found or already finished." });
       return;
     }
 
-    this.#backgroundAgents.delete(sessionId);
+    this.#runningSessions.delete(sessionId);
 
     try {
-      await agent.query.kill();
+      await session.query.kill();
     } catch (err) {
-      log.error({ err, name: agent.name }, "Kill failed");
+      log.error({ err, name: session.name }, "Kill failed");
     }
 
-    this.#callOnResponse({ message: `Killed <b>${escapeHtml(agent.name)}</b>.` });
+    this.#callOnResponse({ message: `Killed <b>${escapeHtml(session.name)}</b>.` });
   }
 
-  handleSessionCommand(): void {
-    this.#callOnResponse({ message: `Session: <code>${this.#mainSessionId ?? "none"}</code>` });
-  }
 
   // --- Internal queue handler ---
 
   async #handleRequest(request: OrchestratorRequest): Promise<void> {
     log.debug({ type: request.type }, "Incoming request");
 
-    // Background result with matching session ID: deliver directly
-    if (request.type === "background-agent-result" && request.sessionId === this.#mainSessionId) {
-      log.debug({ name: request.name }, "Background result on current session, applying directly");
-      await this.#deliverResponse(request.response);
-      return;
+    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)");
+          movedToBackground = mainInfo.prompt;
+        }
+        // If finished: completion handler already delivered the result and removed from map.
+      }
     }
 
     await writeHistoryPrompt(request);
 
-    const result = await this.#queryWithRetry(request);
-    if (!result) return;
-
-    // Update session ID (important after fork or new session)
-    if (result.sessionId !== this.#mainSessionId) {
-      log.info({ oldSessionId: this.#mainSessionId, newSessionId: result.sessionId }, "Session updated");
-      this.#mainSessionId = result.sessionId;
-      saveSessions({ mainSessionId: this.#mainSessionId }, this.#config.settingsDir);
+    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}`;
     }
 
-    await writeHistoryResult(result.value);
-    await this.#deliverResponse(result.value);
+    this.#startMainQuery(prompt, this.#config.model);
   }
 
   // --- Response delivery ---
 
   async #deliverResponse(response: AgentOutput): Promise<void> {
+    await writeHistoryResult(response);
     if (response.action === "send") {
       this.#callOnResponse({
         message: response.message || "[No output]",
@@ -262,53 +287,59 @@ export class Orchestrator {
     });
   }
 
-  // --- Claude calls ---
-
-  async #queryWithRetry(request: OrchestratorRequest): Promise<QueryResult<AgentOutput> | null> {
-    const timeout = request.type === "cron" ? CRON_TIMEOUT : MAIN_TIMEOUT;
-    const query = this.#query(request);
+  // --- Main session query ---
 
-    try {
-      const result = await this.#awaitOrBackground(query, request, timeout);
-      if (!result) return null;
-      return result;
-    } catch (err) {
-      // Resume failed — retry with a fresh session
-      if (err instanceof QueryProcessError && this.#mainSessionId) {
-        log.info("Resume failed, retrying with new session");
-        this.#mainSessionId = undefined;
-        const retryQuery = this.#query(request);
-
-        try {
-          const retryResult = await this.#awaitOrBackground(retryQuery, request, timeout);
-          if (!retryResult) return null;
-          return retryResult;
-        } catch (retryErr) {
-          return { value: this.#errorResponse(retryErr), sessionId: retryQuery.sessionId };
-        }
-      }
+  #startMainQuery(prompt: string, model: string | undefined): void {
+    const opts = { model };
+    let query: RunningQuery<AgentOutput>;
 
-      return { value: this.#errorResponse(err), sessionId: this.#mainSessionId ?? "" };
+    if (this.#mainSessionId && this.#runningSessions.has(this.#mainSessionId)) {
+      query = this.#claude.forkSession(this.#mainSessionId, prompt, responseResultType, opts);
+    } else if (this.#mainSessionId) {
+      query = this.#claude.resumeSession(this.#mainSessionId, prompt, responseResultType, opts);
+    } else {
+      query = this.#claude.newSession(prompt, responseResultType, opts);
     }
-  }
 
-  #query(request: OrchestratorRequest) {
-    const prompt = this.#formatPrompt(request);
-    const model = request.type === "cron" ? (request.model ?? this.#config.model) : this.#config.model;
-    const opts = { model };
+    const sid = query.sessionId;
+    const name = prompt.slice(0, 30).replace(/\s+/g, "-");
+    this.#runningSessions.set(sid, { name, prompt, model, query, lastMessageAt: new Date() });
 
-    // Fork if a background agent is running on the main session
-    if (this.#mainSessionId && this.#backgroundAgents.has(this.#mainSessionId)) {
-      return this.#claude.forkSession(this.#mainSessionId, prompt, responseResultType, opts);
+    if (sid !== this.#mainSessionId) {
+      log.info({ oldSessionId: this.#mainSessionId, newSessionId: sid }, "Session updated");
+      this.#mainSessionId = sid;
+      saveSessions({ mainSessionId: sid }, this.#config.settingsDir);
     }
 
-    // Resume existing session
-    if (this.#mainSessionId) {
-      return this.#claude.resumeSession(this.#mainSessionId, prompt, responseResultType, opts);
-    }
+    log.debug({ name, sessionId: sid }, "Main query started");
 
-    // Start fresh
-    return this.#claude.newSession(prompt, responseResultType, opts);
+    query.result.then(
+      async ({ value: response }) => {
+        if (!this.#runningSessions.has(sid)) {
+          log.error({ name, sessionId: sid }, "Completed session not in runningSessions — delivering anyway");
+          await this.#deliverResponse(response);
+          return;
+        }
+        this.#runningSessions.delete(sid);
+
+        if (sid === this.#mainSessionId) {
+          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");
+          this.#queue.push({ type: "background-agent-result", name, response });
+        }
+      },
+      async (err) => {
+        if (!this.#runningSessions.has(sid)) {
+          log.error({ name, sessionId: sid, err }, "Failed session not in runningSessions — delivering error");
+        } else {
+          this.#runningSessions.delete(sid);
+          log.error({ name, sessionId: sid, err }, "Main query failed");
+        }
+        await this.#deliverResponse(this.#errorResponse(err));
+      },
+    );
   }
 
   #formatPrompt(request: OrchestratorRequest): string {
@@ -327,29 +358,6 @@ export class Orchestrator {
     }
   }
 
-  async #awaitOrBackground(
-    query: RunningQuery<AgentOutput>,
-    request: OrchestratorRequest,
-    timeoutMs: number,
-  ): Promise<QueryResult<AgentOutput> | null> {
-    const result = await Promise.race([
-      query.result,
-      new Promise<null>((resolve) => setTimeout(() => resolve(null), timeoutMs)),
-    ]);
-
-    if (result !== null) return result;
-
-    const name = request.type === "user" ? request.message.slice(0, 30).replace(/\s+/g, "-")
-      : request.type === "cron" ? `cron-${request.name}`
-      : "task";
-    const prompt = this.#formatPrompt(request);
-    const model = request.type === "cron" ? (request.model ?? this.#config.model) : this.#config.model;
-    log.info({ name, sessionId: query.sessionId }, "Request backgrounded due to timeout");
-    this.#callOnResponse({ message: "This is taking longer, continuing in the background." });
-    this.#adoptBackground(name, prompt, model, query);
-    return null;
-  }
-
   #errorResponse(err: unknown): AgentOutput {
     if (err instanceof QueryProcessError) {
       return { action: "send", message: `[Error] Claude exited with code ${err.exitCode}:\n${err.stderr}`, actionReason: "process-error" };
@@ -372,47 +380,27 @@ export class Orchestrator {
     const query = this.#mainSessionId
       ? this.#claude.forkSession(this.#mainSessionId, bgPrompt, responseResultType, { model })
       : this.#claude.newSession(bgPrompt, responseResultType, { model });
-    const sessionId = query.sessionId;
-    const info: BackgroundInfo = { name, prompt, model, query };
-    this.#backgroundAgents.set(sessionId, info);
-
-    log.debug({ name, sessionId }, "Starting background agent");
-
-    query.result.then(
-      async ({ value: response }) => {
-        if (!this.#backgroundAgents.has(sessionId)) return;
-        this.#backgroundAgents.delete(sessionId);
-        log.debug({ name, message: response.message }, "Background agent finished");
-        this.#queue.push({ type: "background-agent-result", name, response });
-      },
-      (err) => {
-        if (!this.#backgroundAgents.has(sessionId)) return;
-        this.#backgroundAgents.delete(sessionId);
-        log.error({ name, err }, "Background agent failed");
-        this.#queue.push({ type: "background-agent-result", name, response: { action: "send", message: `[Error] ${err}`, actionReason: "bg-agent-failed" } });
-      },
-    );
+    this.#registerBackground(name, prompt, model, query);
   }
 
-  #adoptBackground(name: string, prompt: string, model: string | undefined, query: RunningQuery<AgentOutput>) {
-    const sessionId = query.sessionId;
-    const info: BackgroundInfo = { name, prompt, model, query };
-    this.#backgroundAgents.set(sessionId, info);
+  #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() });
 
-    log.debug({ name, sessionId }, "Adopting backgrounded task");
+    log.debug({ name, sessionId: sid }, "Background session registered");
 
     query.result.then(
       ({ value: response }) => {
-        if (!this.#backgroundAgents.has(sessionId)) return;
-        this.#backgroundAgents.delete(sessionId);
-        log.debug({ name }, "Adopted task finished");
-        this.#queue.push({ type: "background-agent-result", name, response, sessionId });
+        if (!this.#runningSessions.has(sid)) return;
+        this.#runningSessions.delete(sid);
+        log.debug({ name, message: response.message }, "Background session finished");
+        this.#queue.push({ type: "background-agent-result", name, response });
       },
       (err) => {
-        if (!this.#backgroundAgents.has(sessionId)) return;
-        this.#backgroundAgents.delete(sessionId);
-        log.error({ name, err }, "Adopted task failed");
-        this.#queue.push({ type: "background-agent-result", name, response: { action: "send", message: `[Error] ${err}`, actionReason: "deferred-failed" }, sessionId });
+        if (!this.#runningSessions.has(sid)) return;
+        this.#runningSessions.delete(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" } });
       },
     );
   }

package/src/prompts.test.ts

@@ -10,7 +10,7 @@ describe("SYSTEM_PROMPT", () => {
     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", () => {

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. \
@@ -28,21 +19,24 @@ 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.
+- 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.
 
 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 [Context: background-result/<name>].
 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.
+
+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.
 
 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.
 
-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.
-
-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.`;