@within-7/minto 0.4.0 → 0.4.2

package/dist/engine/AgentEngine.js

@@ -0,0 +1,902 @@
+import {
+  MessageInjectionChannel
+} from "../services/agentTeams/injectionChannel.js";
+import { AgentHeartbeat } from "../services/agentTeams/heartbeat.js";
+import { query } from "../query.js";
+import { createUserMessage, getLastAssistantMessageId } from "../utils/messages.js";
+import { hasPermissionsToUseTool } from "../permissions.js";
+import { logError } from "../utils/log.js";
+import { debug } from "../utils/debugLogger.js";
+const MAX_ENGINE_MESSAGES = 2e3;
+class AgentEngine {
+  constructor(config) {
+    this.config = config;
+    this._messages = config.initialMessages ? [...config.initialMessages] : [];
+    this._ownMessagesStartIndex = this._messages.length;
+    this.channel = new MessageInjectionChannel();
+    this._canUseTool = config.canUseTool ?? hasPermissionsToUseTool;
+    this._askUser = config.askUser ?? (() => Promise.resolve([]));
+    this._setToolJSX = config.setToolJSX ?? (() => {
+    });
+    this._getBinaryFeedbackResponse = config.getBinaryFeedbackResponse;
+  }
+  // ── State ─────────────────────────────────────────────────
+  _state = "created";
+  _messages = [];
+  listeners = /* @__PURE__ */ new Set();
+  reentryCount = 0;
+  // ── Infrastructure ────────────────────────────────────────
+  channel;
+  heartbeat = null;
+  abortController = null;
+  idleTimer = null;
+  idleResolve = null;
+  // ── Mailbox ───────────────────────────────────────────────
+  pendingFromSubscription = [];
+  unsubMailbox = null;
+  unsubWatcher = null;
+  channelUnsub = null;
+  // ── Dependency injection callbacks ────────────────────────
+  _canUseTool;
+  _askUser;
+  _setToolJSX;
+  _getBinaryFeedbackResponse;
+  // ── Turn timing ───────────────────────────────────────────
+  turnStartTime = null;
+  // ── Idle pause (focus-gated) ────────────────────────────
+  _idlePaused = false;
+  // ── Own messages boundary ───────────────────────────────
+  // For teammate engines initialized with parent messages, this marks
+  // where the engine's OWN messages begin (after the inherited prefix).
+  // Used by the REPL to skip parent messages when rendering a teammate view.
+  _ownMessagesStartIndex = 0;
+  // ── Public API: Read-only state ───────────────────────────
+  get state() {
+    return this._state;
+  }
+  get messages() {
+    return this._messages;
+  }
+  get isRunning() {
+    return this._state === "idle" || this._state === "querying";
+  }
+  /**
+   * Index in messages[] where this engine's OWN messages begin.
+   * For the default engine this is 0 (all messages are its own).
+   * For teammate engines initialized with parent messages, this is
+   * the length of the inherited prefix. Used by the REPL to render
+   * only the agent's own activity when focused on a teammate.
+   */
+  get ownMessagesStartIndex() {
+    return this._ownMessagesStartIndex;
+  }
+  get agentId() {
+    return this.config.agentId;
+  }
+  get injectionChannel() {
+    return this.channel;
+  }
+  // ── Public API: Lifecycle ─────────────────────────────────
+  /**
+   * Initialize the engine: set up heartbeat, mailbox subscription,
+   * and injection channel listener. Transitions to 'idle'.
+   */
+  async start() {
+    if (this._state !== "created") return;
+    this.transition("idle");
+    if (this.config.teamName && this.config.agentId) {
+      this.setupHeartbeat();
+      this.setupMailboxSubscription();
+    }
+    this.channelUnsub = this.channel.onMessage(() => {
+      debug.trace("ENGINE_CHANNEL_ON_MESSAGE", {
+        state: this._state,
+        hasMessages: this.channel.hasMessages()
+      });
+      if (this._state === "idle" && this.channel.hasMessages()) {
+        const pending = this.channel.drain();
+        if (pending.length > 0) {
+          const injectionText = pending.map((m) => m.text).join("\n\n");
+          const injectedMsg = createUserMessage(injectionText);
+          this.emit({ type: "injected_messages", count: pending.length });
+          this.runQueryWithMessages([injectedMsg]).catch((err) => {
+            logError(err);
+            if (this._state === "querying") {
+              this.transition("idle");
+            }
+          });
+        }
+      }
+    });
+  }
+  /**
+   * Submit user input to the engine. Creates a user message and runs the query loop.
+   * If a string is passed, it's wrapped in a createUserMessage.
+   * If Message[] is passed, they're appended directly.
+   */
+  async submitPrompt(input) {
+    if (this._state !== "idle" && this._state !== "created") {
+      if (this._state === "querying" && typeof input === "string") {
+        this.injectMessage(input, "user");
+        return;
+      }
+      return;
+    }
+    this.cancelIdleTimeout();
+    const newMessages = typeof input === "string" ? [createUserMessage(input)] : input;
+    await this.runQueryWithMessages(newMessages);
+  }
+  /**
+   * Inject a message into the channel for between-turns or post-query delivery.
+   */
+  injectMessage(text, source) {
+    this.channel.push(text, source);
+  }
+  /**
+   * Interrupt the current query.
+   */
+  abort() {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+    this.cancelIdleTimeout();
+  }
+  /**
+   * Returns a Promise that resolves when the engine reaches 'idle' or 'stopped'.
+   * Used by foreground adapter to block until the current query completes.
+   */
+  waitForIdle() {
+    if (this._state === "idle" || this._state === "stopped") {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      const unsub = this.on((event) => {
+        if (event.type === "state_change" && (event.to === "idle" || event.to === "stopped")) {
+          unsub();
+          resolve();
+        }
+      });
+    });
+  }
+  /**
+   * Graceful shutdown: abort any running query, stop heartbeat, clean up.
+   */
+  async stop() {
+    if (this._state === "stopped" || this._state === "stopping") return;
+    this.transition("stopping");
+    this.abort();
+    this.heartbeat?.stop();
+    this.unsubMailbox?.();
+    this.unsubWatcher?.();
+    this.channelUnsub?.();
+    this.channel.dispose();
+    this.heartbeat = null;
+    this.unsubMailbox = null;
+    this.unsubWatcher = null;
+    this.channelUnsub = null;
+    this.transition("stopped");
+  }
+  // ── Public API: Event subscription ────────────────────────
+  /**
+   * Subscribe to engine events. Returns an unsubscribe function.
+   */
+  on(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  // ── Public API: Dependency injection ──────────────────────
+  setCanUseTool(fn) {
+    this._canUseTool = fn;
+  }
+  setAskUser(fn) {
+    this._askUser = fn;
+  }
+  setToolJSX(fn) {
+    this._setToolJSX = fn;
+  }
+  setBinaryFeedbackResponse(fn) {
+    this._getBinaryFeedbackResponse = fn;
+  }
+  // ── Public API: Runtime config updates ──────────────────
+  /**
+   * Promote a default/standalone engine to team-lead.
+   * Adds heartbeat + mailbox subscription if the engine is already running.
+   */
+  promoteToTeamLead(teamName) {
+    this.config.role = "team-lead";
+    this.config.teamName = teamName;
+    this.config.agentId = `team-lead@${teamName}`;
+    if (this._state !== "created") {
+      this.setupHeartbeat();
+      this.setupMailboxSubscription();
+    }
+  }
+  /**
+   * Demote from team-lead back to default/standalone. Stops heartbeat,
+   * unsubscribes mailbox, clears team config. Does NOT stop the engine
+   * — it continues running as a standalone agent.
+   *
+   * Must be called when the team is disbanded to prevent stale team
+   * infrastructure (heartbeat, mailbox, channel messages) from triggering
+   * unexpected re-queries after the team is gone.
+   */
+  demoteFromTeamLead() {
+    this.heartbeat?.stop();
+    this.heartbeat = null;
+    this.unsubMailbox?.();
+    this.unsubMailbox = null;
+    this.unsubWatcher?.();
+    this.unsubWatcher = null;
+    this.cancelIdleTimeout();
+    if (this.config.teamName) {
+      try {
+        const { getTeam } = require("../services/agentTeams/teamManager");
+        const entry = getTeam(this.config.teamName);
+        entry?.mailbox.stopAllWatchers();
+      } catch {
+      }
+    }
+    debug.trace("ENGINE_DEMOTE_DRAIN", {
+      channelSize: this.channel.size,
+      state: this._state
+    });
+    this.channel.drain();
+    this.config.role = "default";
+    this.config.teamName = void 0;
+    this.config.agentId = "default";
+  }
+  /**
+   * Update runtime config fields (tools, commands, verbose, etc.).
+   * Does NOT restart the engine — changes take effect on the next query.
+   */
+  /** Fields that can be updated at runtime via updateConfig(). */
+  static MUTABLE_CONFIG_KEYS = /* @__PURE__ */ new Set([
+    "tools",
+    "commands",
+    "verbose",
+    "safeMode",
+    "safetyMode",
+    "maxThinkingTokens",
+    "model",
+    "permissionMode",
+    "readFileTimestamps",
+    "canUseTool",
+    "askUser",
+    "setToolJSX",
+    "getBinaryFeedbackResponse",
+    "onMessage",
+    "onMessagesSet",
+    "isKodingRequest"
+  ]);
+  updateConfig(partial) {
+    for (const key of Object.keys(partial)) {
+      if (AgentEngine.MUTABLE_CONFIG_KEYS.has(key)) {
+        ;
+        this.config[key] = partial[key];
+      }
+    }
+  }
+  /**
+   * Pause/resume idle timeout. When paused, the engine won't time out
+   * even if idleTimeoutMs is set. Used when the engine is focused by the user.
+   */
+  setIdlePaused(paused) {
+    const wasPaused = this._idlePaused;
+    this._idlePaused = paused;
+    if (paused) {
+      this.cancelIdleTimeout();
+      if (this.idleResolve) {
+        const r = this.idleResolve;
+        this.idleResolve = null;
+        r(true);
+      }
+    } else if (wasPaused && this._state === "idle" && this.config.idleTimeoutMs && this.config.idleTimeoutMs > 0) {
+      this.startIdleTimeout().then((wokenUp) => {
+        if (this._state === "stopped" || this._state === "stopping") return;
+        if (wokenUp) {
+          this.drainAndReQuery();
+        } else {
+          this.emit({ type: "idle_timeout" });
+          this.transition("stopping");
+          this.transition("stopped");
+        }
+      }).catch((err) => debug.trace("IDLE_DRAIN_REQUERY", { error: err }));
+    }
+  }
+  /** Read-only access to the engine config. */
+  get engineConfig() {
+    return this.config;
+  }
+  // ── Public API: Message manipulation ──────────────────────
+  /**
+   * Replace the messages array (e.g., for rollback).
+   */
+  setMessages(messages) {
+    this._messages = [...messages];
+    this.emit({ type: "messages_set", messages: this._messages });
+    this.config.onMessagesSet?.(this._messages);
+  }
+  /**
+   * Append messages without triggering a query.
+   */
+  appendMessages(messages) {
+    for (const msg of messages) {
+      this._messages.push(msg);
+      this.emit({ type: "message", message: msg });
+      this.config.onMessage?.(msg);
+    }
+  }
+  /**
+   * Trim messages to MAX_ENGINE_MESSAGES if the array has grown too large.
+   * Keeps the most recent messages to prevent unbounded memory growth.
+   */
+  trimMessages() {
+    if (this._messages.length <= MAX_ENGINE_MESSAGES) return;
+    const originalLength = this._messages.length;
+    let truncated = this._messages.slice(-MAX_ENGINE_MESSAGES);
+    while (truncated.length > 0) {
+      const first = truncated[0];
+      if (!first) break;
+      if (first.type === "user" && Array.isArray(first.message.content) && first.message.content.length > 0 && first.message.content.some(
+        (block) => block.type === "tool_result"
+      )) {
+        truncated.shift();
+      } else if (first.type === "progress") {
+        truncated.shift();
+      } else {
+        break;
+      }
+    }
+    this._messages = truncated;
+    debug.warn("ENGINE_MESSAGES_TRIMMED", {
+      original: originalLength,
+      kept: this._messages.length
+    });
+  }
+  // ── Internal: State machine ───────────────────────────────
+  static VALID_TRANSITIONS = {
+    created: ["idle"],
+    idle: ["querying", "stopping", "stopped"],
+    querying: ["stopping", "idle"],
+    stopping: ["stopped", "idle"],
+    stopped: []
+  };
+  transition(to) {
+    const from = this._state;
+    if (from === to) return;
+    const allowed = AgentEngine.VALID_TRANSITIONS[from];
+    if (allowed && !allowed.includes(to)) {
+      const msg = `Invalid state transition: ${from} \u2192 ${to}`;
+      if (process.env.NODE_ENV === "test") {
+        throw new Error(msg);
+      }
+      debug.warn("INVALID_STATE_TRANSITION", { from, to });
+    }
+    debug.flow("ENGINE_TRANSITION", { from, to });
+    this._state = to;
+    this.emit({ type: "state_change", from, to });
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+      }
+    }
+  }
+  // ── Internal: Setup ───────────────────────────────────────
+  setupHeartbeat() {
+    if (!this.config.teamName || !this.config.agentId) return;
+    this.heartbeat = new AgentHeartbeat();
+    this.heartbeat.start(
+      this.config.agentId,
+      this.config.teamName,
+      this.channel,
+      { interval: this.config.heartbeatIntervalMs ?? 3e3 }
+    );
+  }
+  setupMailboxSubscription() {
+    if (!this.config.teamName || !this.config.agentId) return;
+    try {
+      const { getTeam } = require("../services/agentTeams/teamManager");
+      const teamEntry = getTeam(this.config.teamName);
+      if (teamEntry) {
+        this.unsubMailbox = teamEntry.mailbox.subscribe(
+          this.config.agentId,
+          (msg) => {
+            teamEntry.mailbox.markRead([msg.id]);
+            if (this._state === "idle") {
+              this.formatAndPushToChannel(msg);
+            } else {
+              this.pendingFromSubscription.push(msg);
+            }
+          }
+        );
+        this.unsubWatcher = teamEntry.mailbox.startWatching(this.config.agentId);
+      }
+    } catch (err) {
+      debug.error("ENGINE_MAILBOX_SETUP_FAILED", { error: err });
+    }
+  }
+  /**
+   * Format a team message and push to the injection channel.
+   * Replicates heartbeat formatting logic so subscription-delivered
+   * messages look identical to heartbeat-delivered ones.
+   */
+  formatAndPushToChannel(msg) {
+    try {
+      const {
+        formatTeamMessage,
+        parseIdleNotification,
+        formatIdleNotificationForInjection,
+        humanizeProtocolMessage
+      } = require("../services/agentTeams/messageFormatter");
+      const idleNotif = parseIdleNotification(msg.text);
+      if (idleNotif) {
+        this.channel.push(formatIdleNotificationForInjection(idleNotif), "task");
+      } else {
+        const friendly = humanizeProtocolMessage(msg.text);
+        const formatted = formatTeamMessage(
+          friendly ? { ...msg, summary: friendly } : msg
+        );
+        this.channel.push(formatted, "team");
+      }
+    } catch {
+      this.channel.push(msg.text, "team");
+    }
+  }
+  /**
+   * Ensure heartbeat is running. Called at query boundaries as a safety net.
+   */
+  ensureHeartbeat() {
+    if (!this.config.teamName || !this.config.agentId) return;
+    try {
+      const { getActiveTeams } = require("../services/agentTeams/teamManager");
+      const activeTeams = getActiveTeams();
+      if (activeTeams.length > 0 && !this.heartbeat?.running) {
+        this.setupHeartbeat();
+      }
+    } catch {
+    }
+  }
+  // ── Internal: Query loop ──────────────────────────────────
+  /**
+   * Core method: add messages and run the query loop with post-query drain.
+   */
+  async runQueryWithMessages(newMessages) {
+    if (this._state === "stopping" || this._state === "stopped") return;
+    this.transition("querying");
+    this.reentryCount = 0;
+    this.turnStartTime = Date.now();
+    this.emit({ type: "turn_start" });
+    this.abortController = new AbortController();
+    this.ensureHeartbeat();
+    for (const msg of newMessages) {
+      this._messages.push(msg);
+      this.emit({ type: "message", message: msg });
+      this.config.onMessage?.(msg);
+    }
+    try {
+      await this.executeQueryLoop();
+    } catch (error) {
+      logError(error);
+      this.emit({
+        type: "error",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    } finally {
+      const durationMs = this.turnStartTime ? Date.now() - this.turnStartTime : 0;
+      this.turnStartTime = null;
+      this.abortController = null;
+      this.emit({ type: "turn_end", durationMs });
+      this.ensureHeartbeat();
+      try {
+        if (!this.isAborted()) {
+          const reEntered = await this.postQueryDrain();
+          if (!reEntered) {
+            if (this.channel.hasMessages()) {
+              debug.trace("ENGINE_SAFETY_NET_DRAIN", {
+                channelSize: this.channel.size
+              });
+              const safetyDrained = this.channel.drain();
+              if (safetyDrained.length > 0) {
+                const injectionText = safetyDrained.map((m) => m.text).join("\n\n");
+                const injectedMsg = createUserMessage(injectionText);
+                this.emit({
+                  type: "injected_messages",
+                  count: safetyDrained.length
+                });
+                await this.runReentryTurn(injectedMsg);
+                const reEnteredAgain = await this.postQueryDrain();
+                if (reEnteredAgain) {
+                  return;
+                }
+              }
+            }
+            this.trimMessages();
+            this.transition("idle");
+            if (this.config.idleTimeoutMs && this.config.idleTimeoutMs > 0 && !this._idlePaused) {
+              const wokenUp = await this.startIdleTimeout();
+              if (wokenUp) {
+                this.drainAndReQuery();
+              } else {
+                this.emit({ type: "idle_timeout" });
+                this.transition("stopping");
+                this.transition("stopped");
+              }
+            }
+          }
+        } else {
+          this.transition("idle");
+        }
+      } catch (drainError) {
+        debug.error("ENGINE_POST_DRAIN_ERROR", {
+          error: drainError,
+          channelSize: this.channel.size
+        });
+        logError(drainError);
+        this.emit({
+          type: "error",
+          error: drainError instanceof Error ? drainError : new Error(String(drainError))
+        });
+        if (this.channel.hasMessages()) {
+          const salvaged = this.channel.drain();
+          if (salvaged.length > 0) {
+            debug.trace("ENGINE_SALVAGED_MESSAGES", { count: salvaged.length });
+            const txt = salvaged.map((m) => m.text).join("\n\n");
+            const msg = createUserMessage(txt);
+            this._messages.push(msg);
+            this.emit({ type: "message", message: msg });
+          }
+        }
+        if (this._state === "querying") {
+          this.transition("idle");
+        }
+      }
+    }
+  }
+  /**
+   * Execute the inner query loop with post-loop mailbox drain.
+   * When the model finishes (no more tool_use), checks the mailbox —
+   * if messages arrived, re-enters query() so the agent can respond.
+   */
+  async executeQueryLoop() {
+    const maxTurns = this.config.maxTurns ?? 0;
+    let keepRunning = true;
+    while (keepRunning) {
+      keepRunning = false;
+      const [systemPrompt, context] = await this.resolvePromptAndContext();
+      const queryOptions = this.buildQueryOptions();
+      for await (const message of query(
+        this._messages.filter((m) => !("localOnly" in m && m.localOnly)),
+        systemPrompt,
+        context,
+        this._canUseTool,
+        {
+          abortController: this.abortController,
+          options: queryOptions,
+          messageId: getLastAssistantMessageId(this._messages),
+          agentId: this.config.agentId,
+          readFileTimestamps: this.config.readFileTimestamps ?? {},
+          setToolJSX: this._setToolJSX,
+          askUser: this._askUser,
+          injectionChannel: this.channel
+        },
+        this._getBinaryFeedbackResponse
+      )) {
+        this._messages.push(message);
+        this.emit({ type: "message", message });
+        this.config.onMessage?.(message);
+        if (message.type !== "assistant") {
+          continue;
+        }
+        if (maxTurns > 0 && this.getAssistantTurnCount() >= maxTurns) break;
+      }
+      debug.trace("ENGINE_QUERY_LOOP_POST", {
+        isAborted: this.isAborted(),
+        maxTurns,
+        assistantTurns: this.getAssistantTurnCount(),
+        channelSize: this.channel.size
+      });
+      if (!this.isAborted() && !(maxTurns > 0 && this.getAssistantTurnCount() >= maxTurns)) {
+        const drained = this.drainChannelInline();
+        debug.trace("ENGINE_DRAIN_INLINE", { drained });
+        if (drained) keepRunning = true;
+        if (this.config.teamName) {
+          if (this.drainMailbox()) keepRunning = true;
+        }
+      }
+    }
+  }
+  /** Hard ceiling on total re-entries across all recursive postQueryDrain calls. */
+  static MAX_GLOBAL_REENTRY = 20;
+  /**
+   * Execute a single re-entry turn: push the injected message, emit events,
+   * create a fresh AbortController, run the query loop, and finalize.
+   * Consolidates the 15-line pattern that was duplicated in 4 places.
+   */
+  async runReentryTurn(injectedMsg) {
+    this._messages.push(injectedMsg);
+    this.emit({ type: "message", message: injectedMsg });
+    this.config.onMessage?.(injectedMsg);
+    this.turnStartTime = Date.now();
+    this.abortController = new AbortController();
+    this.emit({ type: "turn_start" });
+    try {
+      await this.executeQueryLoop();
+    } catch (error) {
+      logError(error);
+      this.emit({
+        type: "error",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    } finally {
+      const durationMs = this.turnStartTime ? Date.now() - this.turnStartTime : 0;
+      this.turnStartTime = null;
+      this.abortController = null;
+      this.emit({ type: "turn_end", durationMs });
+    }
+  }
+  /**
+   * Post-query drain: check injection channel and direct mailbox.
+   * Uses iterative loop instead of recursion to bound call stack depth.
+   * Returns true if re-entry was triggered.
+   */
+  async postQueryDrain() {
+    const maxReentry = this.config.maxReentry ?? 10;
+    let didReenter = false;
+    while (true) {
+      debug.trace("ENGINE_POST_QUERY_DRAIN", {
+        channelSize: this.channel.size,
+        reentryCount: this.reentryCount,
+        maxReentry
+      });
+      if (this.reentryCount >= AgentEngine.MAX_GLOBAL_REENTRY) {
+        debug.warn("ENGINE_GLOBAL_REENTRY_LIMIT", {
+          reentryCount: this.reentryCount,
+          limit: AgentEngine.MAX_GLOBAL_REENTRY
+        });
+        break;
+      }
+      const pending = this.channel.drain();
+      if (pending.length > 0 && this.reentryCount < maxReentry) {
+        this.reentryCount++;
+        didReenter = true;
+        const injectionText = pending.map((m) => m.text).join("\n\n");
+        const injectedMsg = createUserMessage(injectionText);
+        this.emit({ type: "injected_messages", count: pending.length });
+        await this.runReentryTurn(injectedMsg);
+        continue;
+      }
+      if (this.config.teamName) {
+        try {
+          const { getTeam } = require("../services/agentTeams/teamManager");
+          const entry = getTeam(this.config.teamName);
+          if (entry && this.config.agentId) {
+            const unread = entry.mailbox.getUnread(this.config.agentId);
+            if (unread.length > 0 && this.reentryCount < maxReentry) {
+              this.reentryCount++;
+              didReenter = true;
+              const { formatTeamMessage } = require("../services/agentTeams/messageFormatter");
+              const formatted = unread.map((m) => formatTeamMessage(m)).join("\n\n");
+              entry.mailbox.markRead(unread.map((m) => m.id));
+              const injectedMsg = createUserMessage(formatted);
+              await this.runReentryTurn(injectedMsg);
+              continue;
+            }
+          }
+        } catch {
+        }
+      }
+      break;
+    }
+    return didReenter;
+  }
+  // ── Internal: Channel + Mailbox drain ─────────────────────
+  /**
+   * Drain the injection channel inline: move pending channel messages
+   * into the conversation as a user message. Universal — works for
+   * any agent type (standalone, team-lead, teammate).
+   *
+   * Returns true if messages were injected.
+   */
+  drainChannelInline() {
+    const pending = this.channel.drain();
+    if (pending.length === 0) return false;
+    const injectionText = pending.map((m) => m.text).join("\n\n");
+    const injectedMsg = createUserMessage(injectionText);
+    this._messages.push(injectedMsg);
+    this.emit({ type: "message", message: injectedMsg });
+    this.config.onMessage?.(injectedMsg);
+    this.emit({ type: "injected_messages", count: pending.length });
+    return true;
+  }
+  /**
+   * Drain pending mailbox messages and inject them into the conversation.
+   * Returns true if messages were injected.
+   */
+  drainMailbox() {
+    if (!this.config.teamName) return false;
+    let injected = false;
+    try {
+      const { getTeam } = require("../services/agentTeams/teamManager");
+      const teamEntry = getTeam(this.config.teamName);
+      if (!teamEntry || !this.config.agentId) return false;
+      const fromSub = this.pendingFromSubscription.splice(0);
+      const unread = teamEntry.mailbox.getUnread(this.config.agentId);
+      const allNew = [...fromSub];
+      const seenIds = new Set(fromSub.map((m) => m.id));
+      for (const m of unread) {
+        if (!seenIds.has(m.id)) allNew.push(m);
+      }
+      if (allNew.length === 0) return false;
+      const {
+        formatTeamMessagesForInjection,
+        formatUserGuidanceForInjection,
+        humanizeProtocolMessage
+      } = require("../services/agentTeams/messageFormatter");
+      const userMsgs = allNew.filter((m) => m.from === "user");
+      const teamMsgs = allNew.filter((m) => m.from !== "user");
+      const humanizedTeamMsgs = teamMsgs.map((m) => {
+        const friendly = humanizeProtocolMessage(m.text);
+        return friendly ? { ...m, summary: friendly } : m;
+      });
+      if (userMsgs.length > 0) {
+        const guidanceText = userMsgs.map((m) => formatUserGuidanceForInjection(m.text)).join("\n\n");
+        const guidanceMsg = createUserMessage(guidanceText);
+        this._messages.push(guidanceMsg);
+        this.emit({ type: "message", message: guidanceMsg });
+        this.config.onMessage?.(guidanceMsg);
+        injected = true;
+      }
+      if (humanizedTeamMsgs.length > 0) {
+        const deliveryText = formatTeamMessagesForInjection(humanizedTeamMsgs);
+        const injectedMsg = createUserMessage(deliveryText);
+        this._messages.push(injectedMsg);
+        this.emit({ type: "message", message: injectedMsg });
+        this.config.onMessage?.(injectedMsg);
+        injected = true;
+      }
+      teamEntry.mailbox.markRead(allNew.map((m) => m.id));
+    } catch {
+    }
+    return injected;
+  }
+  // ── Internal: Idle timeout ────────────────────────────────
+  /**
+   * Wait for the configured idle timeout. Returns true if woken up
+   * by arriving messages, false if the timeout expired or was aborted.
+   */
+  startIdleTimeout() {
+    const timeoutMs = this.config.idleTimeoutMs ?? 0;
+    if (timeoutMs <= 0) return Promise.resolve(false);
+    return new Promise((resolve) => {
+      if (this.pendingFromSubscription.length > 0) {
+        resolve(true);
+        return;
+      }
+      this.idleResolve = resolve;
+      this.idleTimer = setTimeout(() => {
+        this.idleResolve = null;
+        this.idleTimer = null;
+        resolve(false);
+      }, timeoutMs);
+      if (this.config.teamName && this.config.agentId) {
+        try {
+          const { getTeam } = require("../services/agentTeams/teamManager");
+          const teamEntry = getTeam(this.config.teamName);
+          if (teamEntry) {
+            this.unsubMailbox?.();
+            this.unsubMailbox = teamEntry.mailbox.subscribe(
+              this.config.agentId,
+              (msg) => {
+                this.pendingFromSubscription.push(msg);
+                teamEntry.mailbox.markRead([msg.id]);
+                this.cancelIdleTimeout();
+                if (this.idleResolve) {
+                  const r = this.idleResolve;
+                  this.idleResolve = null;
+                  r(true);
+                }
+              }
+            );
+          }
+        } catch {
+        }
+      }
+      this.idleAbortController = new AbortController();
+      const handler = () => {
+        this.cancelIdleTimeout();
+        if (this.idleResolve) {
+          const r = this.idleResolve;
+          this.idleResolve = null;
+          r(false);
+        }
+      };
+      this.idleAbortController.signal.addEventListener("abort", handler, {
+        once: true
+      });
+    });
+  }
+  /** Dedicated abort controller for idle timeout, independent of query abort. */
+  idleAbortController = null;
+  cancelIdleTimeout() {
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    if (this.idleAbortController) {
+      this.idleAbortController.abort();
+      this.idleAbortController = null;
+    }
+  }
+  /**
+   * Drain mailbox and re-enter query loop (used after idle wake-up).
+   * Uses a synthetic empty message as the trigger since drainMailbox()
+   * already pushed the actual messages into this._messages.
+   */
+  async drainAndReQuery() {
+    const drained = this.drainMailbox();
+    if (!drained) return;
+    this.transition("querying");
+    this.turnStartTime = Date.now();
+    this.abortController = new AbortController();
+    this.emit({ type: "turn_start" });
+    try {
+      await this.executeQueryLoop();
+    } catch (error) {
+      logError(error);
+      this.emit({
+        type: "error",
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    } finally {
+      const durationMs = this.turnStartTime ? Date.now() - this.turnStartTime : 0;
+      this.turnStartTime = null;
+      this.abortController = null;
+      this.emit({ type: "turn_end", durationMs });
+      this.transition("idle");
+    }
+  }
+  // ── Internal: Helpers ─────────────────────────────────────
+  isAborted() {
+    return this.abortController?.signal.aborted ?? false;
+  }
+  getAssistantTurnCount() {
+    return this._messages.filter((m) => m.type === "assistant").length;
+  }
+  /**
+   * Resolve system prompt and context (supports both pre-built and async factory).
+   */
+  async resolvePromptAndContext() {
+    const [systemPrompt, context] = await Promise.all([
+      typeof this.config.systemPrompt === "function" ? this.config.systemPrompt() : Promise.resolve(this.config.systemPrompt),
+      typeof this.config.context === "function" ? this.config.context() : Promise.resolve(this.config.context)
+    ]);
+    return [systemPrompt, context];
+  }
+  /**
+   * Build query options from engine config.
+   */
+  buildQueryOptions() {
+    return {
+      commands: this.config.commands ?? [],
+      forkNumber: this.config.forkNumber ?? 0,
+      messageLogName: this.config.messageLogName ?? "agent",
+      tools: this.config.tools,
+      verbose: this.config.verbose ?? false,
+      safeMode: this.config.safeMode,
+      safetyMode: this.config.safetyMode,
+      permissionMode: this.config.permissionMode,
+      maxThinkingTokens: this.config.maxThinkingTokens ?? 0,
+      isKodingRequest: this.config.isKodingRequest,
+      model: this.config.model
+    };
+  }
+}
+export {
+  AgentEngine
+};
+//# sourceMappingURL=AgentEngine.js.map