@ch4p/cli 0.1.3 → 0.1.4

package/dist/chunk-4IRZQCRN.js

@@ -0,0 +1,1832 @@
+import {
+  EngineError,
+  ToolError,
+  abortableSleep,
+  backoffDelay
+} from "./chunk-YSCX2QQQ.js";
+
+// ../../packages/agent/dist/index.js
+import { Worker } from "worker_threads";
+import { EventEmitter } from "events";
+import { setMaxListeners } from "events";
+import { homedir } from "os";
+var SteeringQueue = class {
+  queue = [];
+  /**
+   * Push a message into the queue. The queue is re-sorted on every push
+   * so that drain() always returns messages in priority-then-timestamp order.
+   */
+  push(msg) {
+    this.queue.push(msg);
+    this.queue.sort((a, b) => {
+      const pa = a.priority ?? 0;
+      const pb = b.priority ?? 0;
+      if (pa !== pb) return pb - pa;
+      return a.timestamp.getTime() - b.timestamp.getTime();
+    });
+  }
+  /**
+   * Drain all messages from the queue, returning them in priority order.
+   * After this call the queue is empty.
+   */
+  drain() {
+    const messages = this.queue;
+    this.queue = [];
+    return messages;
+  }
+  /** Peek at the highest-priority message without removing it. */
+  peek() {
+    return this.queue[0];
+  }
+  /** Returns true if any pending message is an abort request. */
+  hasAbort() {
+    return this.queue.some((m) => m.type === "abort");
+  }
+  /** Returns true if the queue has any pending messages. */
+  hasMessages() {
+    return this.queue.length > 0;
+  }
+  /** Discard all pending messages. */
+  clear() {
+    this.queue = [];
+  }
+  /** Number of messages currently in the queue. */
+  get length() {
+    return this.queue.length;
+  }
+};
+var NAMED_STRATEGIES = {
+  /** Aggressive sliding window — keeps only the 3 most recent exchanges. */
+  sliding_window_3: {
+    name: "sliding_window_3",
+    type: "sliding",
+    compactionTarget: 0.4,
+    keepRatio: 0.2,
+    preserveRecentToolPairs: 3,
+    preserveTaskDescription: true,
+    description: "Aggressive sliding window. Best for long multi-step tasks where older context is less relevant."
+  },
+  /** Conservative sliding — preserves more history for tasks that need it. */
+  sliding_conservative: {
+    name: "sliding_conservative",
+    type: "sliding",
+    compactionTarget: 0.7,
+    keepRatio: 0.5,
+    preserveRecentToolPairs: 5,
+    preserveTaskDescription: true,
+    description: "Conservative sliding window. Best for tasks that reference earlier context frequently."
+  },
+  /** Summarize with high keep ratio — good for coding tasks. */
+  summarize_coding: {
+    name: "summarize_coding",
+    type: "summarize",
+    compactionTarget: 0.6,
+    keepRatio: 0.4,
+    preserveRecentToolPairs: 4,
+    preserveTaskDescription: true,
+    description: "Summarize old context while keeping recent code-related tool calls. Best for coding tasks."
+  },
+  /** Drop oldest with task description pinning. */
+  drop_oldest_pinned: {
+    name: "drop_oldest_pinned",
+    type: "drop_oldest",
+    compactionTarget: 0.5,
+    preserveRecentToolPairs: 2,
+    preserveTaskDescription: true,
+    description: "Drop oldest messages but always preserve the original task and recent tool calls."
+  }
+};
+function estimateTokens(msg) {
+  if (typeof msg.content === "string") {
+    return Math.ceil(msg.content.length / 4);
+  }
+  let chars = 0;
+  for (const block of msg.content) {
+    if (block.text) chars += block.text.length;
+    if (block.toolOutput) chars += block.toolOutput.length;
+    if (block.toolInput) chars += JSON.stringify(block.toolInput).length;
+  }
+  return Math.ceil(chars / 4);
+}
+function isToolResultMessage(msg) {
+  return msg.role === "tool" || msg.toolCallId !== void 0 && msg.toolCallId !== "";
+}
+function hasToolCalls(msg) {
+  return msg.role === "assistant" && Array.isArray(msg.toolCalls) && msg.toolCalls.length > 0;
+}
+var ContextManager = class {
+  messages = [];
+  systemPrompt = null;
+  tokenEstimate = 0;
+  maxTokens;
+  compactionThreshold;
+  strategyType;
+  namedStrategy;
+  summarizer;
+  constructor(opts = {}) {
+    this.maxTokens = opts.maxTokens ?? 1e5;
+    this.compactionThreshold = opts.compactionThreshold ?? 0.85;
+    this.summarizer = opts.summarizer;
+    if (typeof opts.strategy === "object" && opts.strategy !== null) {
+      this.namedStrategy = opts.strategy;
+      this.strategyType = opts.strategy.type;
+    } else {
+      this.namedStrategy = null;
+      this.strategyType = opts.strategy ?? "sliding";
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /** Set or replace the system prompt (always position 0). */
+  setSystemPrompt(prompt) {
+    const msg = { role: "system", content: prompt };
+    if (this.systemPrompt) {
+      this.tokenEstimate -= estimateTokens(this.systemPrompt);
+    }
+    this.systemPrompt = msg;
+    this.tokenEstimate += estimateTokens(msg);
+  }
+  /** Append a message to the context. Triggers compaction if over threshold. */
+  async addMessage(msg) {
+    const tokens = estimateTokens(msg);
+    this.messages.push(msg);
+    this.tokenEstimate += tokens;
+    if (this.tokenEstimate > this.maxTokens * this.compactionThreshold) {
+      await this.compact();
+    }
+  }
+  /** Return the full message array (system prompt + conversation). */
+  getMessages() {
+    if (this.systemPrompt) {
+      return [this.systemPrompt, ...this.messages];
+    }
+    return [...this.messages];
+  }
+  /** Return the current approximate token usage. */
+  getTokenEstimate() {
+    return this.tokenEstimate;
+  }
+  /** Return the configured maximum token budget. */
+  getMaxTokens() {
+    return this.maxTokens;
+  }
+  /** Return the active strategy name. */
+  getStrategyName() {
+    return this.namedStrategy?.name ?? this.strategyType;
+  }
+  /** Return the full named strategy config if one is active. */
+  getNamedStrategy() {
+    return this.namedStrategy;
+  }
+  /** Remove all conversation messages (keeps system prompt). */
+  clear() {
+    this.messages = [];
+    this.tokenEstimate = this.systemPrompt ? estimateTokens(this.systemPrompt) : 0;
+  }
+  // -----------------------------------------------------------------------
+  // Compaction
+  // -----------------------------------------------------------------------
+  /**
+   * Compact the context to fit within the token budget.
+   *
+   * This is invoked automatically when `addMessage` pushes the estimate past
+   * the compaction threshold, but can also be called manually.
+   */
+  async compact() {
+    switch (this.strategyType) {
+      case "drop_oldest":
+        this.compactDropOldest();
+        break;
+      case "summarize":
+        await this.compactSummarize();
+        break;
+      case "sliding":
+        await this.compactSliding();
+        break;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Strategy 1: drop_oldest — remove oldest messages, preserving tool pairs
+  // -----------------------------------------------------------------------
+  compactDropOldest() {
+    const target = this.maxTokens * (this.namedStrategy?.compactionTarget ?? 0.6);
+    let idx = 0;
+    const protectedIndices = this.getProtectedIndices();
+    while (this.tokenEstimate > target && idx < this.messages.length - 1) {
+      const msg = this.messages[idx];
+      if (protectedIndices.has(idx)) {
+        idx++;
+        continue;
+      }
+      if (hasToolCalls(msg)) {
+        const groupEnd = this.findToolGroupEnd(idx);
+        let groupProtected = false;
+        for (let i = idx; i <= groupEnd; i++) {
+          if (protectedIndices.has(i)) {
+            groupProtected = true;
+            break;
+          }
+        }
+        if (groupProtected) {
+          idx = groupEnd + 1;
+          continue;
+        }
+        const dropped = this.messages.splice(idx, groupEnd - idx + 1);
+        for (const d of dropped) this.tokenEstimate -= estimateTokens(d);
+        continue;
+      }
+      if (isToolResultMessage(msg)) {
+        idx++;
+        continue;
+      }
+      this.messages.splice(idx, 1);
+      this.tokenEstimate -= estimateTokens(msg);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Strategy 2: summarize — collapse old messages into one summary message
+  // -----------------------------------------------------------------------
+  async compactSummarize() {
+    if (!this.summarizer) {
+      this.compactDropOldest();
+      return;
+    }
+    const keepRatio = this.namedStrategy?.keepRatio ?? 0.3;
+    const keepCount = Math.max(2, Math.floor(this.messages.length * keepRatio));
+    const splitIdx = this.messages.length - keepCount;
+    if (this.namedStrategy?.preserveTaskDescription) {
+      const firstUserIdx = this.messages.findIndex((m) => m.role === "user");
+      if (firstUserIdx >= 0 && firstUserIdx < splitIdx) {
+      }
+    }
+    const toSummarize = this.messages.slice(0, splitIdx);
+    const toKeep = this.messages.slice(splitIdx);
+    if (toSummarize.length === 0) return;
+    let taskDescription;
+    if (this.namedStrategy?.preserveTaskDescription) {
+      const firstUser = toSummarize.find((m) => m.role === "user");
+      if (firstUser) {
+        taskDescription = firstUser;
+      }
+    }
+    const summary = await this.summarizer(toSummarize);
+    const summaryMsg = {
+      role: "system",
+      content: `[Conversation summary]
+${summary}`
+    };
+    if (taskDescription) {
+      this.messages = [taskDescription, summaryMsg, ...toKeep];
+    } else {
+      this.messages = [summaryMsg, ...toKeep];
+    }
+    this.recalculateTokens();
+  }
+  // -----------------------------------------------------------------------
+  // Strategy 3: sliding — sliding window with summary prefix
+  // -----------------------------------------------------------------------
+  async compactSliding() {
+    if (!this.summarizer) {
+      this.compactDropOldest();
+      return;
+    }
+    const compactionTarget = this.namedStrategy?.compactionTarget ?? 0.6;
+    const targetTokens = this.maxTokens * compactionTarget;
+    let windowTokens = 0;
+    let windowStart = this.messages.length;
+    const preserveToolPairs = this.namedStrategy?.preserveRecentToolPairs ?? 3;
+    let toolPairsFound = 0;
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const msgTokens = estimateTokens(this.messages[i]);
+      if (windowTokens + msgTokens > targetTokens && toolPairsFound >= preserveToolPairs) break;
+      if (isToolResultMessage(this.messages[i]) && i > 0 && hasToolCalls(this.messages[i - 1])) {
+        windowTokens += msgTokens + estimateTokens(this.messages[i - 1]);
+        windowStart = i - 1;
+        toolPairsFound++;
+        i--;
+      } else {
+        windowTokens += msgTokens;
+        windowStart = i;
+        if (hasToolCalls(this.messages[i])) {
+          toolPairsFound++;
+        }
+      }
+    }
+    if (windowStart <= 0) return;
+    const toSummarize = this.messages.slice(0, windowStart);
+    const window = this.messages.slice(windowStart);
+    if (toSummarize.length === 0) return;
+    let taskDescription;
+    if (this.namedStrategy?.preserveTaskDescription) {
+      const firstUser = toSummarize.find((m) => m.role === "user");
+      if (firstUser) {
+        taskDescription = firstUser;
+      }
+    }
+    const summary = await this.summarizer(toSummarize);
+    const summaryMsg = {
+      role: "system",
+      content: `[Conversation summary]
+${summary}`
+    };
+    if (taskDescription) {
+      this.messages = [taskDescription, summaryMsg, ...window];
+    } else {
+      this.messages = [summaryMsg, ...window];
+    }
+    this.recalculateTokens();
+  }
+  // -----------------------------------------------------------------------
+  // AWM: Protected message index computation
+  // -----------------------------------------------------------------------
+  /**
+   * Compute the set of message indices that should never be compacted away.
+   * This implements the AWM insight that preserving task description and
+   * recent tool interactions dramatically improves task success rates.
+   */
+  getProtectedIndices() {
+    const protected_ = /* @__PURE__ */ new Set();
+    if (this.namedStrategy?.preserveTaskDescription !== false) {
+      const firstUserIdx = this.messages.findIndex((m) => m.role === "user");
+      if (firstUserIdx >= 0) {
+        protected_.add(firstUserIdx);
+      }
+    }
+    if (this.namedStrategy?.pinnedRoles) {
+      for (let i = 0; i < this.messages.length; i++) {
+        if (this.namedStrategy.pinnedRoles.includes(this.messages[i].role)) {
+          protected_.add(i);
+        }
+      }
+    }
+    const preserveCount = this.namedStrategy?.preserveRecentToolPairs ?? 0;
+    if (preserveCount > 0) {
+      let pairsFound = 0;
+      for (let i = this.messages.length - 1; i >= 0 && pairsFound < preserveCount; i--) {
+        if (hasToolCalls(this.messages[i])) {
+          protected_.add(i);
+          const groupEnd = this.findToolGroupEnd(i);
+          for (let j = i; j <= groupEnd; j++) {
+            protected_.add(j);
+          }
+          pairsFound++;
+        }
+      }
+    }
+    return protected_;
+  }
+  // -----------------------------------------------------------------------
+  // Internal helpers
+  // -----------------------------------------------------------------------
+  /**
+   * Given the index of an assistant message with tool calls, find the index
+   * of the last related tool-result message that immediately follows it.
+   */
+  findToolGroupEnd(assistantIdx) {
+    let end = assistantIdx;
+    for (let i = assistantIdx + 1; i < this.messages.length; i++) {
+      if (isToolResultMessage(this.messages[i])) {
+        end = i;
+      } else {
+        break;
+      }
+    }
+    return end;
+  }
+  /** Recompute tokenEstimate from scratch. */
+  recalculateTokens() {
+    this.tokenEstimate = this.systemPrompt ? estimateTokens(this.systemPrompt) : 0;
+    for (const msg of this.messages) {
+      this.tokenEstimate += estimateTokens(msg);
+    }
+  }
+};
+var DEFAULT_WORKER_SCRIPT = `
+const { parentPort } = require('node:worker_threads');
+
+parentPort.on('message', async (msg) => {
+  if (msg.type === 'execute') {
+    try {
+      // In production the worker would look up the tool in a registry.
+      // Here we simply return an error indicating the tool is not loaded.
+      parentPort.postMessage({
+        type: 'result',
+        result: {
+          success: false,
+          output: '',
+          error: 'Worker has no tool registry \u2014 provide a workerScript.',
+        },
+      });
+    } catch (err) {
+      parentPort.postMessage({
+        type: 'error',
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+});
+`;
+var ToolWorkerPool = class extends EventEmitter {
+  workers = [];
+  taskQueue = [];
+  shuttingDown = false;
+  maxWorkers;
+  taskTimeoutMs;
+  workerScript;
+  // Stats
+  totalTasks = 0;
+  completedTasks = 0;
+  failedTasks = 0;
+  totalDurationMs = 0;
+  stubWarned = false;
+  constructor(opts = {}) {
+    super();
+    this.maxWorkers = opts.maxWorkers ?? 4;
+    this.taskTimeoutMs = opts.taskTimeoutMs ?? 6e4;
+    this.workerScript = opts.workerScript;
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /**
+   * Execute a tool task in a worker thread. Returns a promise that resolves
+   * with the ToolResult. If `signal` is already aborted the task is rejected
+   * immediately.
+   */
+  execute(task, signal, onProgress = () => {
+  }) {
+    if (this.shuttingDown) {
+      return Promise.reject(new Error("Worker pool is shutting down"));
+    }
+    if (signal?.aborted) {
+      return Promise.reject(new Error("Task aborted before execution"));
+    }
+    this.totalTasks++;
+    return new Promise((resolve, reject) => {
+      const queued = { task, signal, onProgress, resolve, reject };
+      if (signal) {
+        const onAbort = () => {
+          const idx = this.taskQueue.indexOf(queued);
+          if (idx !== -1) {
+            this.taskQueue.splice(idx, 1);
+            this.failedTasks++;
+            reject(new Error("Task aborted while queued"));
+          }
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+      }
+      const idle = this.getIdleWorker();
+      if (idle) {
+        this.dispatch(idle, queued);
+      } else if (this.workers.length < this.maxWorkers) {
+        const managed = this.spawnWorker();
+        this.dispatch(managed, queued);
+      } else {
+        this.taskQueue.push(queued);
+      }
+    });
+  }
+  /** Gracefully shut down the pool: finish in-flight tasks, then terminate. */
+  async shutdown() {
+    this.shuttingDown = true;
+    for (const q of this.taskQueue) {
+      this.failedTasks++;
+      q.reject(new Error("Worker pool shutting down"));
+    }
+    this.taskQueue = [];
+    const terminatePromises = this.workers.map((mw) => {
+      if (mw.currentTimer) clearTimeout(mw.currentTimer);
+      return mw.worker.terminate();
+    });
+    await Promise.allSettled(terminatePromises);
+    this.workers = [];
+  }
+  /** Check whether a real worker script is configured (not the default stub). */
+  hasWorkerScript() {
+    return this.workerScript !== void 0;
+  }
+  /** Return current pool statistics. */
+  getStats() {
+    const activeWorkers = this.workers.filter((w) => w.busy).length;
+    return {
+      totalTasks: this.totalTasks,
+      completedTasks: this.completedTasks,
+      failedTasks: this.failedTasks,
+      activeTasks: activeWorkers,
+      queuedTasks: this.taskQueue.length,
+      avgDurationMs: this.completedTasks > 0 ? Math.round(this.totalDurationMs / this.completedTasks) : 0,
+      workerCount: this.workers.length,
+      idleWorkers: this.workers.filter((w) => !w.busy).length
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Internal
+  // -----------------------------------------------------------------------
+  spawnWorker() {
+    let worker;
+    if (this.workerScript) {
+      worker = new Worker(this.workerScript);
+    } else {
+      if (!this.stubWarned) {
+        this.stubWarned = true;
+        this.emit("worker_stub", "Using default worker stub \u2014 heavyweight tools will fail. Build the worker script or provide workerScript option.");
+      }
+      worker = new Worker(DEFAULT_WORKER_SCRIPT, { eval: true });
+    }
+    const managed = {
+      worker,
+      busy: false,
+      taskCount: 0
+    };
+    worker.on("error", (err) => {
+      this.emit("worker_error", err);
+      this.handleWorkerCrash(managed, err);
+    });
+    worker.on("exit", (code) => {
+      if (code !== 0 && !this.shuttingDown) {
+        this.emit("worker_exit", code);
+        this.removeWorker(managed);
+      }
+    });
+    this.workers.push(managed);
+    return managed;
+  }
+  getIdleWorker() {
+    return this.workers.find((w) => !w.busy);
+  }
+  dispatch(managed, queued) {
+    managed.busy = true;
+    managed.taskCount++;
+    const startTime = Date.now();
+    const { task, signal, onProgress, resolve, reject } = queued;
+    const handler = (msg) => {
+      if (msg.type === "progress" && msg.update) {
+        onProgress(msg.update);
+        return;
+      }
+      if (msg.type === "result" && msg.result) {
+        cleanup();
+        const duration = Date.now() - startTime;
+        this.completedTasks++;
+        this.totalDurationMs += duration;
+        managed.worker.removeListener("message", handler);
+        resolve(msg.result);
+        this.dispatchNext();
+        return;
+      }
+      if (msg.type === "error") {
+        cleanup();
+        this.failedTasks++;
+        managed.worker.removeListener("message", handler);
+        resolve({
+          success: false,
+          output: "",
+          error: msg.message ?? "Unknown worker error"
+        });
+        this.dispatchNext();
+        return;
+      }
+    };
+    managed.currentTimer = setTimeout(() => {
+      this.failedTasks++;
+      managed.busy = false;
+      if (managed.currentTimer) clearTimeout(managed.currentTimer);
+      managed.currentTimer = void 0;
+      managed.worker.removeListener("message", handler);
+      try {
+        managed.worker.postMessage({ type: "abort" });
+      } catch {
+      }
+      managed.worker.terminate().catch(() => {
+      });
+      this.removeWorker(managed);
+      reject(new Error(`Tool "${task.tool}" timed out after ${this.taskTimeoutMs}ms`));
+      this.dispatchNext();
+    }, this.taskTimeoutMs);
+    let abortListener;
+    if (signal) {
+      abortListener = () => {
+        if (managed.currentTimer) clearTimeout(managed.currentTimer);
+        managed.currentTimer = void 0;
+        managed.busy = false;
+        this.failedTasks++;
+        managed.worker.removeListener("message", handler);
+        try {
+          managed.worker.postMessage({ type: "abort" });
+        } catch {
+        }
+        managed.worker.terminate().catch(() => {
+        });
+        this.removeWorker(managed);
+        reject(new Error("Task aborted during execution"));
+        this.dispatchNext();
+      };
+      signal.addEventListener("abort", abortListener, { once: true });
+    }
+    const cleanup = () => {
+      if (managed.currentTimer) clearTimeout(managed.currentTimer);
+      managed.currentTimer = void 0;
+      managed.busy = false;
+      if (abortListener && signal) {
+        signal.removeEventListener("abort", abortListener);
+      }
+    };
+    managed.worker.on("message", handler);
+    managed.worker.postMessage({
+      type: "execute",
+      tool: task.tool,
+      args: task.args,
+      context: task.context
+    });
+  }
+  dispatchNext() {
+    if (this.taskQueue.length === 0) return;
+    if (this.shuttingDown) return;
+    const idle = this.getIdleWorker();
+    if (idle) {
+      const next = this.taskQueue.shift();
+      if (next.signal?.aborted) {
+        this.failedTasks++;
+        next.reject(new Error("Task aborted while queued"));
+        this.dispatchNext();
+        return;
+      }
+      this.dispatch(idle, next);
+    } else if (this.workers.length < this.maxWorkers) {
+      const managed = this.spawnWorker();
+      const next = this.taskQueue.shift();
+      if (next.signal?.aborted) {
+        this.failedTasks++;
+        next.reject(new Error("Task aborted while queued"));
+        this.dispatchNext();
+        return;
+      }
+      this.dispatch(managed, next);
+    }
+  }
+  handleWorkerCrash(managed, _err) {
+    if (managed.currentTimer) clearTimeout(managed.currentTimer);
+    managed.currentTimer = void 0;
+    this.removeWorker(managed);
+    this.dispatchNext();
+  }
+  removeWorker(managed) {
+    const idx = this.workers.indexOf(managed);
+    if (idx !== -1) {
+      this.workers.splice(idx, 1);
+    }
+  }
+};
+var Session = class {
+  config;
+  context;
+  steering;
+  metadata;
+  state;
+  constructor(config, opts = {}) {
+    this.config = config;
+    this.state = "created";
+    this.context = opts.sharedContext ?? new ContextManager(opts.contextOpts);
+    this.steering = new SteeringQueue();
+    this.metadata = {
+      id: config.sessionId,
+      channelId: config.channelId,
+      userId: config.userId,
+      engineId: config.engineId,
+      startedAt: /* @__PURE__ */ new Date(),
+      state: this.state,
+      loopIterations: 0,
+      toolInvocations: 0,
+      llmCalls: 0,
+      errors: []
+    };
+    if (config.systemPrompt) {
+      this.context.setSystemPrompt(config.systemPrompt);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Accessors
+  // -----------------------------------------------------------------------
+  getId() {
+    return this.config.sessionId;
+  }
+  getConfig() {
+    return this.config;
+  }
+  getContext() {
+    return this.context;
+  }
+  getSteering() {
+    return this.steering;
+  }
+  getState() {
+    return this.state;
+  }
+  getMetadata() {
+    return { ...this.metadata, state: this.state };
+  }
+  // -----------------------------------------------------------------------
+  // Lifecycle transitions
+  // -----------------------------------------------------------------------
+  /** Transition to active. Only valid from created or paused. */
+  activate() {
+    if (this.state !== "created" && this.state !== "paused") {
+      throw new Error(`Cannot activate session in state "${this.state}"`);
+    }
+    this.state = "active";
+    this.metadata.state = this.state;
+  }
+  /** Pause the session. Only valid from active. */
+  pause() {
+    if (this.state !== "active") {
+      throw new Error(`Cannot pause session in state "${this.state}"`);
+    }
+    this.state = "paused";
+    this.metadata.state = this.state;
+  }
+  /** Resume from paused back to active. */
+  resume() {
+    if (this.state !== "paused") {
+      throw new Error(`Cannot resume session in state "${this.state}"`);
+    }
+    this.state = "active";
+    this.metadata.state = this.state;
+  }
+  /** Mark the session as successfully completed. */
+  complete() {
+    if (this.state !== "active" && this.state !== "paused") {
+      throw new Error(`Cannot complete session in state "${this.state}"`);
+    }
+    this.state = "completed";
+    this.metadata.state = this.state;
+    this.metadata.endedAt = /* @__PURE__ */ new Date();
+    this.steering.clear();
+  }
+  /** Mark the session as failed with an error. */
+  fail(error) {
+    this.metadata.errors.push(error);
+    if (this.metadata.errors.length > 20) {
+      this.metadata.errors.shift();
+    }
+    this.state = "failed";
+    this.metadata.state = this.state;
+    this.metadata.endedAt = /* @__PURE__ */ new Date();
+    this.steering.clear();
+  }
+  // -----------------------------------------------------------------------
+  // Stats tracking
+  // -----------------------------------------------------------------------
+  /** Increment loop iteration counter. */
+  recordIteration() {
+    this.metadata.loopIterations++;
+  }
+  /** Increment tool invocation counter. */
+  recordToolInvocation() {
+    this.metadata.toolInvocations++;
+  }
+  /** Increment LLM call counter. */
+  recordLLMCall() {
+    this.metadata.llmCalls++;
+  }
+  /** Record an error without failing the session (capped to prevent unbounded growth). */
+  recordError(error) {
+    this.metadata.errors.push(error);
+    if (this.metadata.errors.length > 20) {
+      this.metadata.errors.shift();
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Cleanup
+  // -----------------------------------------------------------------------
+  /** Clear all session resources. */
+  dispose() {
+    this.context.clear();
+    this.steering.clear();
+  }
+};
+function sanitizeWorkspacePath(cwd) {
+  const home = homedir();
+  if (cwd === home) return ".";
+  if (cwd.startsWith(home + "/")) {
+    return "./" + cwd.slice(home.length + 1);
+  }
+  return cwd;
+}
+var MAX_TOOL_RESULTS = 30;
+var MAX_TOOL_OUTPUT_LEN = 65536;
+var MAX_STATE_RECORDS = 20;
+var PERMISSIVE_POLICY = {
+  autonomyLevel: "full",
+  validatePath: (_path, _op) => ({ allowed: true }),
+  validateCommand: (_cmd, _args) => ({ allowed: true }),
+  requiresConfirmation: () => false,
+  audit: () => [],
+  sanitizeOutput: (text) => ({ clean: text, redacted: false }),
+  validateInput: () => ({ safe: true, threats: [] })
+};
+function toolDefinitionsFrom(tools) {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    parameters: t.parameters
+  }));
+}
+var AgentLoop = class {
+  session;
+  engine;
+  tools;
+  toolDefs;
+  observer;
+  opts;
+  abortController = null;
+  currentHandle = null;
+  workerPool;
+  ownsWorkerPool;
+  /** Accumulated state snapshots for verification (AWM). */
+  stateRecords = [];
+  /** Accumulated tool results for verification (AWM). */
+  allToolResults = [];
+  /** Cumulative token usage across all iterations. */
+  cumulativeTokens = { inputTokens: 0, outputTokens: 0 };
+  constructor(session, engine, tools, observer, opts = {}) {
+    this.session = session;
+    this.engine = engine;
+    this.observer = observer;
+    this.tools = new Map(tools.map((t) => [t.name, t]));
+    this.toolDefs = toolDefinitionsFrom(tools);
+    if (opts.workerPool) {
+      this.workerPool = opts.workerPool;
+      this.ownsWorkerPool = false;
+    } else {
+      this.workerPool = new ToolWorkerPool();
+      this.ownsWorkerPool = true;
+    }
+    this.opts = {
+      maxIterations: opts.maxIterations ?? 50,
+      maxRetries: opts.maxRetries ?? 3,
+      workerPool: this.workerPool,
+      verifier: opts.verifier,
+      enableStateSnapshots: opts.enableStateSnapshots ?? true,
+      memoryBackend: opts.memoryBackend,
+      securityPolicy: opts.securityPolicy,
+      toolContextExtensions: opts.toolContextExtensions,
+      onBeforeFirstRun: opts.onBeforeFirstRun,
+      onAfterComplete: opts.onAfterComplete
+    };
+  }
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+  /** Return the session ID for this agent loop. */
+  getSessionId() {
+    return this.session.getId();
+  }
+  /**
+   * Run the agent loop, returning an async iterable of AgentEvents.
+   * The loop continues until the engine signals completion, the iteration
+   * limit is reached, or the run is aborted.
+   */
+  async *run(initialMessage) {
+    this.abortController = new AbortController();
+    const signal = this.abortController.signal;
+    try {
+      setMaxListeners(this.opts.maxIterations + 5, signal);
+    } catch {
+    }
+    this.stateRecords = [];
+    this.allToolResults = [];
+    this.session.activate();
+    this.observer.onSessionStart({
+      sessionId: this.session.getId(),
+      channelId: this.session.getConfig().channelId,
+      userId: this.session.getConfig().userId,
+      engineId: this.session.getConfig().engineId,
+      startedAt: /* @__PURE__ */ new Date()
+    });
+    await this.session.getContext().addMessage({
+      role: "user",
+      content: initialMessage
+    });
+    if (this.opts.onBeforeFirstRun) {
+      try {
+        await this.opts.onBeforeFirstRun(this.session.getContext());
+      } catch {
+      }
+    }
+    let iterations = 0;
+    let consecutiveErrors = 0;
+    let done = false;
+    let finalAnswer = "";
+    try {
+      while (!done && iterations < this.opts.maxIterations) {
+        iterations++;
+        this.session.recordIteration();
+        const steeringResult = this.processSteering();
+        if (steeringResult.abort) {
+          yield { type: "aborted", reason: steeringResult.abortReason };
+          return;
+        }
+        if (signal.aborted) {
+          yield { type: "aborted", reason: "Signal aborted" };
+          return;
+        }
+        const job = {
+          sessionId: this.session.getId(),
+          messages: this.session.getContext().getMessages(),
+          tools: this.toolDefs.length > 0 ? this.toolDefs : void 0,
+          systemPrompt: this.session.getConfig().systemPrompt,
+          model: this.session.getConfig().model
+        };
+        let handle;
+        try {
+          handle = await this.engine.startRun(job, { signal });
+          this.currentHandle = handle;
+          this.session.recordLLMCall();
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          consecutiveErrors++;
+          this.session.recordError(error);
+          this.observer.onError(error, { phase: "engine_start", iteration: iterations });
+          const nonRetryable = error instanceof EngineError && !error.retryable;
+          if (nonRetryable || consecutiveErrors >= this.opts.maxRetries) {
+            yield { type: "error", error };
+            done = true;
+            break;
+          }
+          await abortableSleep(backoffDelay(consecutiveErrors), signal);
+          continue;
+        }
+        consecutiveErrors = 0;
+        let accumulatedText = "";
+        const pendingToolCalls = [];
+        let completionAnswer;
+        let completionUsage;
+        let engineErrored = false;
+        let lastEngineError;
+        try {
+          for await (const event of handle.events) {
+            if (signal.aborted) {
+              await handle.cancel();
+              yield { type: "aborted", reason: "Signal aborted" };
+              return;
+            }
+            if (this.session.getSteering().hasAbort()) {
+              await handle.cancel();
+              const reason = this.drainAbortReason();
+              yield { type: "aborted", reason };
+              return;
+            }
+            yield* this.handleEngineEvent(
+              event,
+              accumulatedText,
+              pendingToolCalls
+            );
+            if (event.type === "text_delta") {
+              accumulatedText += event.delta;
+            }
+            if (event.type === "completed") {
+              completionAnswer = event.answer;
+              completionUsage = event.usage;
+              if (completionUsage) {
+                this.cumulativeTokens.inputTokens += completionUsage.inputTokens;
+                this.cumulativeTokens.outputTokens += completionUsage.outputTokens;
+              }
+            }
+            if (event.type === "error") {
+              engineErrored = true;
+              lastEngineError = event.error;
+              break;
+            }
+          }
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          consecutiveErrors++;
+          this.session.recordError(error);
+          this.observer.onError(error, { phase: "engine_stream", iteration: iterations });
+          const nonRetryable = error instanceof EngineError && !error.retryable;
+          if (nonRetryable || consecutiveErrors >= this.opts.maxRetries) {
+            yield { type: "error", error };
+            done = true;
+            break;
+          }
+          await abortableSleep(backoffDelay(consecutiveErrors), signal);
+          continue;
+        }
+        if (engineErrored) {
+          consecutiveErrors++;
+          const nonRetryable = lastEngineError instanceof EngineError && !lastEngineError.retryable;
+          if (nonRetryable || consecutiveErrors >= this.opts.maxRetries) {
+            yield { type: "error", error: lastEngineError ?? new EngineError("Engine returned error", this.engine.id) };
+            done = true;
+            break;
+          }
+          await abortableSleep(backoffDelay(consecutiveErrors), signal);
+          continue;
+        }
+        if (completionAnswer !== void 0 && pendingToolCalls.length === 0) {
+          await this.session.getContext().addMessage({
+            role: "assistant",
+            content: completionAnswer
+          });
+          finalAnswer = completionAnswer;
+          yield { type: "complete", answer: completionAnswer, usage: completionUsage };
+          done = true;
+          break;
+        }
+        if (pendingToolCalls.length > 0) {
+          await this.session.getContext().addMessage({
+            role: "assistant",
+            content: accumulatedText || "",
+            toolCalls: pendingToolCalls
+          });
+          for (const toolCall of pendingToolCalls) {
+            const preToolSteering = this.processSteering();
+            if (preToolSteering.abort) {
+              yield { type: "aborted", reason: preToolSteering.abortReason };
+              return;
+            }
+            if (signal.aborted) {
+              yield { type: "aborted", reason: "Signal aborted" };
+              return;
+            }
+            const validationResult = this.validateToolCall(toolCall);
+            if (validationResult !== null) {
+              yield {
+                type: "tool_validation_error",
+                tool: toolCall.name,
+                errors: validationResult.errors ?? ["Validation failed"]
+              };
+              await this.session.getContext().addMessage({
+                role: "tool",
+                content: `[VALIDATION ERROR] Invalid arguments for tool "${toolCall.name}": ${validationResult.errors?.join(", ") ?? "validation failed"}. Please fix the arguments and try again.`,
+                toolCallId: toolCall.id
+              });
+              this.session.recordToolInvocation();
+              continue;
+            }
+            yield { type: "tool_start", tool: toolCall.name, args: toolCall.args };
+            const result = await this.executeTool(toolCall, signal);
+            const cappedResult = { ...result };
+            if (cappedResult.output && cappedResult.output.length > MAX_TOOL_OUTPUT_LEN) {
+              cappedResult.output = cappedResult.output.slice(0, MAX_TOOL_OUTPUT_LEN) + "\n[truncated]";
+            }
+            if (cappedResult.error && cappedResult.error.length > MAX_TOOL_OUTPUT_LEN) {
+              cappedResult.error = cappedResult.error.slice(0, MAX_TOOL_OUTPUT_LEN) + "\n[truncated]";
+            }
+            this.allToolResults.push(cappedResult);
+            if (this.allToolResults.length > MAX_TOOL_RESULTS) {
+              this.allToolResults.shift();
+            }
+            yield { type: "tool_end", tool: toolCall.name, result };
+            const rawContent = result.output || result.error || "";
+            const policy = this.opts.securityPolicy ?? PERMISSIVE_POLICY;
+            const sanitized = policy.sanitizeOutput(rawContent);
+            if (sanitized.redacted) {
+              this.observer.onSecurityEvent({
+                type: "secret_redacted",
+                details: {
+                  source: "tool_output",
+                  tool: toolCall.name,
+                  patterns: sanitized.redactedPatterns
+                },
+                timestamp: /* @__PURE__ */ new Date()
+              });
+            }
+            await this.session.getContext().addMessage({
+              role: "tool",
+              content: sanitized.clean,
+              toolCallId: toolCall.id
+            });
+            this.session.recordToolInvocation();
+          }
+          continue;
+        }
+        if (accumulatedText) {
+          await this.session.getContext().addMessage({
+            role: "assistant",
+            content: accumulatedText
+          });
+          finalAnswer = accumulatedText;
+          yield { type: "complete", answer: accumulatedText, usage: completionUsage };
+          done = true;
+        }
+      }
+      if (!done) {
+        const error = new Error(`Agent loop exceeded maximum iterations (${this.opts.maxIterations})`);
+        yield { type: "error", error };
+        this.session.fail(error);
+        return;
+      }
+      if (this.opts.verifier && finalAnswer) {
+        try {
+          const verificationResult = await this.opts.verifier.verify({
+            taskDescription: initialMessage,
+            finalAnswer,
+            messages: this.session.getContext().getMessages(),
+            toolResults: this.allToolResults,
+            stateSnapshots: this.stateRecords
+          });
+          yield { type: "verification", result: verificationResult };
+          if (verificationResult.outcome === "partial" || verificationResult.outcome === "failure") {
+            const suggestions = verificationResult.suggestions?.join("\n- ") ?? "No specific suggestions.";
+            const feedback = `[VERIFICATION ${verificationResult.outcome.toUpperCase()}] ${verificationResult.reasoning}
+Suggestions:
+- ${suggestions}`;
+            this.observer.onError(
+              new Error(`Task verification: ${verificationResult.outcome}`),
+              {
+                phase: "verification",
+                confidence: verificationResult.confidence,
+                issues: verificationResult.issues?.length ?? 0
+              }
+            );
+            await this.session.getContext().addMessage({
+              role: "system",
+              content: feedback
+            });
+          }
+        } catch (err) {
+          this.observer.onError(
+            err instanceof Error ? err : new Error(String(err)),
+            { phase: "verification" }
+          );
+        }
+      }
+      this.session.complete();
+      if (this.opts.onAfterComplete && finalAnswer) {
+        try {
+          await this.opts.onAfterComplete(this.session.getContext(), finalAnswer);
+        } catch {
+        }
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      yield { type: "error", error };
+      this.session.fail(error);
+    } finally {
+      this.currentHandle = null;
+      this.observer.onSessionEnd(
+        {
+          sessionId: this.session.getId(),
+          channelId: this.session.getConfig().channelId,
+          userId: this.session.getConfig().userId,
+          engineId: this.session.getConfig().engineId,
+          startedAt: this.session.getMetadata().startedAt
+        },
+        {
+          duration: Date.now() - this.session.getMetadata().startedAt.getTime(),
+          toolInvocations: this.session.getMetadata().toolInvocations,
+          llmCalls: this.session.getMetadata().llmCalls,
+          tokensUsed: {
+            inputTokens: this.cumulativeTokens.inputTokens,
+            outputTokens: this.cumulativeTokens.outputTokens
+          },
+          errors: this.session.getMetadata().errors.length
+        }
+      );
+      if (this.ownsWorkerPool) {
+        await this.workerPool.shutdown();
+      }
+      await this.observer.flush?.();
+    }
+  }
+  /** Abort the running loop with a reason. */
+  abort(reason) {
+    this.session.getSteering().push({
+      type: "abort",
+      content: reason,
+      priority: 100,
+      // highest
+      timestamp: /* @__PURE__ */ new Date()
+    });
+    this.abortController?.abort(reason);
+  }
+  /** Push a live steering message into the session's queue. */
+  steer(message) {
+    this.session.getSteering().push(message);
+  }
+  /**
+   * Forward a raw string to the engine's stdin.
+   * Used to respond to permission prompts from SubprocessEngine (e.g. claude-cli).
+   */
+  steerEngine(message) {
+    this.currentHandle?.steer(message);
+  }
+  /** Get accumulated state records for external inspection. */
+  getStateRecords() {
+    return this.stateRecords;
+  }
+  /** Get accumulated tool results for external inspection. */
+  getToolResults() {
+    return this.allToolResults;
+  }
+  // -----------------------------------------------------------------------
+  // Engine event handling
+  // -----------------------------------------------------------------------
+  *handleEngineEvent(event, accumulatedText, pendingToolCalls) {
+    switch (event.type) {
+      case "text_delta":
+        yield {
+          type: "text",
+          delta: event.delta,
+          partial: accumulatedText + event.delta
+        };
+        break;
+      case "tool_start":
+        pendingToolCalls.push({
+          id: event.id,
+          name: event.tool,
+          args: event.args
+        });
+        break;
+      case "tool_progress":
+        yield { type: "tool_progress", tool: "", update: event.update };
+        break;
+      case "tool_end":
+        yield { type: "tool_end", tool: "", result: event.result };
+        break;
+      case "error":
+        yield { type: "error", error: event.error };
+        break;
+      case "completed":
+        break;
+      case "started":
+        break;
+    }
+  }
+  // -----------------------------------------------------------------------
+  // AWM: Mandatory step-level tool call validation
+  // -----------------------------------------------------------------------
+  /**
+   * Validate a tool call's arguments before execution.
+   * Returns null if validation passes, or a ValidationResult with errors.
+   *
+   * This is a mandatory step — if a tool does not implement validate(),
+   * we perform basic structural checks (args must be an object or undefined).
+   */
+  validateToolCall(toolCall) {
+    const tool = this.tools.get(toolCall.name);
+    if (!tool) {
+      return { errors: [`Tool "${toolCall.name}" not found.`] };
+    }
+    if (tool.validate) {
+      const result = tool.validate(toolCall.args);
+      if (!result.valid) {
+        return { errors: result.errors ?? ["Validation failed."] };
+      }
+      return null;
+    }
+    if (toolCall.args !== void 0 && toolCall.args !== null) {
+      if (typeof toolCall.args !== "object" || Array.isArray(toolCall.args)) {
+        return { errors: ["Arguments must be an object."] };
+      }
+    }
+    return null;
+  }
+  // -----------------------------------------------------------------------
+  // Tool execution (with AWM state snapshots)
+  // -----------------------------------------------------------------------
+  async executeTool(toolCall, signal) {
+    const tool = this.tools.get(toolCall.name);
+    if (!tool) {
+      const error = new ToolError(`Unknown tool: ${toolCall.name}`, toolCall.name);
+      this.observer.onError(error, { tool: toolCall.name });
+      return {
+        success: false,
+        output: "",
+        error: `Tool "${toolCall.name}" not found`
+      };
+    }
+    const startTime = Date.now();
+    const rawCwd = this.session.getConfig().cwd ?? process.cwd();
+    const toolContext = {
+      sessionId: this.session.getId(),
+      cwd: sanitizeWorkspacePath(rawCwd),
+      securityPolicy: this.opts.securityPolicy ?? PERMISSIVE_POLICY,
+      abortSignal: signal,
+      onProgress: (_update) => {
+      },
+      // Inject memory backend so memory_store / memory_recall tools can access it.
+      ...this.opts.memoryBackend ? { memoryBackend: this.opts.memoryBackend } : {},
+      // Spread any domain-specific extensions (e.g. canvasState for canvas tool).
+      ...this.opts.toolContextExtensions ?? {}
+    };
+    let beforeSnapshot;
+    if (this.opts.enableStateSnapshots && tool.getStateSnapshot) {
+      try {
+        beforeSnapshot = await tool.getStateSnapshot(toolCall.args, toolContext);
+      } catch {
+      }
+    }
+    let result;
+    try {
+      if (tool.weight === "heavyweight" && this.opts.workerPool?.hasWorkerScript?.()) {
+        result = await this.workerPool.execute(
+          {
+            tool: toolCall.name,
+            args: toolCall.args,
+            context: {
+              sessionId: this.session.getId(),
+              cwd: sanitizeWorkspacePath(rawCwd)
+            }
+          },
+          signal,
+          (_update) => {
+          }
+        );
+      } else {
+        result = await tool.execute(toolCall.args, toolContext);
+      }
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      result = {
+        success: false,
+        output: "",
+        error: error.message
+      };
+    }
+    let afterSnapshot;
+    if (this.opts.enableStateSnapshots && tool.getStateSnapshot) {
+      try {
+        afterSnapshot = await tool.getStateSnapshot(toolCall.args, toolContext);
+        result.stateSnapshot = afterSnapshot;
+      } catch {
+      }
+    }
+    if (beforeSnapshot || afterSnapshot) {
+      this.stateRecords.push({
+        tool: toolCall.name,
+        args: toolCall.args,
+        before: beforeSnapshot,
+        after: afterSnapshot
+      });
+      if (this.stateRecords.length > MAX_STATE_RECORDS) {
+        this.stateRecords.shift();
+      }
+    }
+    const duration = Date.now() - startTime;
+    this.observer.onToolInvocation({
+      sessionId: this.session.getId(),
+      tool: toolCall.name,
+      args: toolCall.args,
+      result,
+      duration,
+      error: result.success ? void 0 : new Error(result.error ?? "Tool failed")
+    });
+    return result;
+  }
+  // -----------------------------------------------------------------------
+  // Steering
+  // -----------------------------------------------------------------------
+  /**
+   * Drain the steering queue and process all messages. Returns an object
+   * indicating whether an abort was requested.
+   */
+  processSteering() {
+    const steering = this.session.getSteering();
+    if (!steering.hasMessages()) {
+      return { abort: false };
+    }
+    const messages = steering.drain();
+    let abort = false;
+    let abortReason;
+    for (const msg of messages) {
+      switch (msg.type) {
+        case "abort":
+          abort = true;
+          abortReason = msg.content ?? "Abort requested";
+          break;
+        case "inject": {
+          if (msg.content) {
+            const injectMsg = {
+              role: "user",
+              content: msg.content
+            };
+            this.session.getContext().addMessage(injectMsg).catch((err) => {
+              this.session.recordError(
+                err instanceof Error ? err : new Error(String(err))
+              );
+            });
+          }
+          break;
+        }
+        case "priority":
+          if (msg.content) {
+            const priorityMsg = {
+              role: "user",
+              content: `[PRIORITY] ${msg.content}`
+            };
+            this.session.getContext().addMessage(priorityMsg).catch((err) => {
+              this.session.recordError(
+                err instanceof Error ? err : new Error(String(err))
+              );
+            });
+          }
+          break;
+        case "context_update":
+          if (msg.content) {
+            this.session.getContext().setSystemPrompt(msg.content);
+          }
+          break;
+      }
+    }
+    return { abort, abortReason };
+  }
+  /**
+   * Extract the abort reason from a pending abort message.
+   */
+  drainAbortReason() {
+    const messages = this.session.getSteering().drain();
+    const abortMsg = messages.find((m) => m.type === "abort");
+    return abortMsg?.content ?? "Abort requested";
+  }
+};
+function builtinRules(opts) {
+  return [
+    {
+      id: "non-empty-answer",
+      description: "Final answer must not be empty",
+      check: (ctx) => {
+        if (!ctx.finalAnswer || ctx.finalAnswer.trim().length < opts.minAnswerLength) {
+          return `Final answer is empty or too short (minimum ${opts.minAnswerLength} characters)`;
+        }
+        return null;
+      }
+    },
+    {
+      id: "tool-success-ratio",
+      description: "Tool error ratio must be below threshold",
+      check: (ctx) => {
+        if (ctx.toolResults.length === 0) return null;
+        const errors = ctx.toolResults.filter((r) => !r.success).length;
+        const ratio = errors / ctx.toolResults.length;
+        if (ratio > opts.maxToolErrorRatio) {
+          return `${errors}/${ctx.toolResults.length} tool calls failed (${(ratio * 100).toFixed(0)}% error rate, max allowed ${(opts.maxToolErrorRatio * 100).toFixed(0)}%)`;
+        }
+        return null;
+      }
+    },
+    {
+      id: "no-error-only-answer",
+      description: "Final answer should not consist solely of an error message",
+      check: (ctx) => {
+        const lower = ctx.finalAnswer.toLowerCase().trim();
+        if (lower.startsWith("error:") || lower.startsWith("i encountered an error")) {
+          return "Final answer appears to be an error message rather than a real response";
+        }
+        return null;
+      },
+      severity: "warning"
+    },
+    {
+      id: "task-reference",
+      description: "Final answer should reference the task",
+      check: (ctx) => {
+        const taskWords = ctx.taskDescription.toLowerCase().split(/\W+/).filter((w) => w.length > 4);
+        if (taskWords.length === 0) return null;
+        const answerLower = ctx.finalAnswer.toLowerCase();
+        const matches = taskWords.filter((w) => answerLower.includes(w));
+        if (matches.length === 0) {
+          return "Final answer does not appear to reference any key terms from the original task";
+        }
+        return null;
+      },
+      severity: "warning"
+    },
+    {
+      id: "state-consistency",
+      description: "State snapshots should show changes for write operations",
+      check: (ctx) => {
+        for (const record of ctx.stateSnapshots) {
+          if (record.before && record.after) {
+            const beforeKeys = Object.keys(record.before.state);
+            const afterKeys = Object.keys(record.after.state);
+            if (beforeKeys.length > 0 && afterKeys.length > 0) {
+              const identical = beforeKeys.every(
+                (k) => JSON.stringify(record.before.state[k]) === JSON.stringify(record.after.state[k])
+              );
+              if (identical && afterKeys.every((k) => beforeKeys.includes(k))) {
+                return `Tool "${record.tool}" produced identical before/after state \u2014 may not have executed correctly`;
+              }
+            }
+          }
+        }
+        return null;
+      },
+      severity: "info"
+    }
+  ];
+}
+var FormatVerifier = class {
+  id = "format-verifier";
+  name = "Format Verifier";
+  rules;
+  constructor(opts = {}) {
+    const resolvedOpts = {
+      minAnswerLength: opts.minAnswerLength ?? 1,
+      maxToolErrorRatio: opts.maxToolErrorRatio ?? 0.5
+    };
+    this.rules = [
+      ...opts.skipBuiltinRules ? [] : builtinRules(resolvedOpts),
+      ...opts.customRules ?? []
+    ];
+  }
+  async checkFormat(context) {
+    const errors = [];
+    for (const rule of this.rules) {
+      const result = rule.check(context);
+      if (result !== null && (rule.severity ?? "error") === "error") {
+        errors.push(`[${rule.id}] ${result}`);
+      }
+    }
+    return {
+      passed: errors.length === 0,
+      errors: errors.length > 0 ? errors : void 0
+    };
+  }
+  async verify(context) {
+    const formatCheck = await this.checkFormat(context);
+    const issues = [];
+    for (const rule of this.rules) {
+      const result = rule.check(context);
+      if (result !== null) {
+        issues.push({
+          severity: rule.severity ?? "error",
+          message: `[${rule.id}] ${result}`
+        });
+      }
+    }
+    const errorCount = issues.filter((i) => i.severity === "error").length;
+    const warningCount = issues.filter((i) => i.severity === "warning").length;
+    let outcome;
+    let confidence;
+    if (errorCount > 0) {
+      outcome = "failure";
+      confidence = Math.max(0, 1 - errorCount * 0.3);
+    } else if (warningCount > 0) {
+      outcome = "partial";
+      confidence = Math.max(0.5, 1 - warningCount * 0.15);
+    } else {
+      outcome = "success";
+      confidence = 1;
+    }
+    const suggestions = issues.filter((i) => i.severity === "error" || i.severity === "warning").map((i) => `Fix: ${i.message}`);
+    return {
+      outcome,
+      confidence,
+      reasoning: formatCheck.passed ? `All ${this.rules.length} format checks passed.` : `${errorCount} error(s) and ${warningCount} warning(s) found across ${this.rules.length} checks.`,
+      issues: issues.length > 0 ? issues : void 0,
+      suggestions: suggestions.length > 0 ? suggestions : void 0,
+      formatCheck
+    };
+  }
+};
+var JUDGE_SYSTEM_PROMPT = `You are a task verification judge. Your job is to assess whether an AI agent correctly completed a user's task.
+
+You will receive:
+1. The original task the user requested
+2. The agent's final answer
+3. A summary of tool calls the agent made
+
+Evaluate the following criteria:
+- **Completeness**: Did the agent fully address the task?
+- **Correctness**: Is the agent's answer accurate and appropriate?
+- **Quality**: Is the answer well-structured and useful?
+
+Respond in EXACTLY this JSON format (no markdown, no code fences):
+{"score": <number 0-100>, "passed": <boolean>, "reasoning": "<brief explanation>", "issues": [{"severity": "<error|warning|info>", "message": "<issue description>"}]}
+
+Score guide: 0-30 = failure, 31-70 = partial, 71-100 = success.
+Set "passed" to true only if score >= 71.`;
+function buildJudgePrompt(context, maxToolResults) {
+  const parts = [];
+  parts.push(`## Original Task
+${context.taskDescription}`);
+  parts.push(`
+## Agent's Final Answer
+${context.finalAnswer}`);
+  if (context.toolResults.length > 0) {
+    const results = context.toolResults.slice(0, maxToolResults);
+    const toolSummary = results.map((r, i) => {
+      const status = r.success ? "\u2713" : "\u2717";
+      const output = r.output ? r.output.length > 200 ? r.output.slice(0, 200) + "..." : r.output : "(no output)";
+      const error = r.error ? ` | Error: ${r.error}` : "";
+      return `${i + 1}. ${status} ${output}${error}`;
+    });
+    parts.push(`
+## Tool Call Results (${context.toolResults.length} total)
+${toolSummary.join("\n")}`);
+    if (context.toolResults.length > maxToolResults) {
+      parts.push(`
+(${context.toolResults.length - maxToolResults} additional tool results omitted)`);
+    }
+  }
+  if (context.stateSnapshots.length > 0) {
+    const diffs = context.stateSnapshots.filter((s) => s.before || s.after).slice(0, 5).map((s) => {
+      const before = s.before ? JSON.stringify(s.before.state) : "(none)";
+      const after = s.after ? JSON.stringify(s.after.state) : "(none)";
+      return `- ${s.tool}: before=${before.slice(0, 100)}, after=${after.slice(0, 100)}`;
+    });
+    if (diffs.length > 0) {
+      parts.push(`
+## State Changes
+${diffs.join("\n")}`);
+    }
+  }
+  return parts.join("\n");
+}
+function parseJudgeResponse(text) {
+  let jsonStr = text.trim();
+  const fenceMatch = jsonStr.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+  if (fenceMatch) {
+    jsonStr = fenceMatch[1].trim();
+  }
+  try {
+    const parsed = JSON.parse(jsonStr);
+    return {
+      score: Math.max(0, Math.min(100, typeof parsed.score === "number" ? parsed.score : 0)),
+      passed: typeof parsed.passed === "boolean" ? parsed.passed : parsed.score >= 71,
+      reasoning: typeof parsed.reasoning === "string" ? parsed.reasoning : "No reasoning provided.",
+      issues: Array.isArray(parsed.issues) ? parsed.issues : void 0
+    };
+  } catch {
+    const scoreMatch = text.match(/score["\s:]+(\d+)/i);
+    const score = scoreMatch ? parseInt(scoreMatch[1], 10) : 50;
+    return {
+      score,
+      passed: score >= 71,
+      reasoning: `Failed to parse structured judge response. Raw text: ${text.slice(0, 200)}`
+    };
+  }
+}
+var LLMVerifier = class {
+  id = "llm-verifier";
+  name = "LLM Verifier";
+  provider;
+  model;
+  formatVerifier;
+  maxJudgeTokens;
+  temperature;
+  skipSemanticOnFormatFailure;
+  maxToolResultsInPrompt;
+  constructor(opts) {
+    this.provider = opts.provider;
+    this.model = opts.model;
+    this.formatVerifier = new FormatVerifier(opts.formatOpts);
+    this.maxJudgeTokens = opts.maxJudgeTokens ?? 1024;
+    this.temperature = opts.temperature ?? 0;
+    this.skipSemanticOnFormatFailure = opts.skipSemanticOnFormatFailure ?? true;
+    this.maxToolResultsInPrompt = opts.maxToolResultsInPrompt ?? 20;
+  }
+  async checkFormat(context) {
+    return this.formatVerifier.checkFormat(context);
+  }
+  async checkSemantic(context) {
+    const judgePrompt = buildJudgePrompt(context, this.maxToolResultsInPrompt);
+    const messages = [
+      { role: "user", content: judgePrompt }
+    ];
+    const result = await this.provider.complete(this.model, messages, {
+      systemPrompt: JUDGE_SYSTEM_PROMPT,
+      maxTokens: this.maxJudgeTokens,
+      temperature: this.temperature
+    });
+    const responseText = typeof result.message.content === "string" ? result.message.content : "";
+    const judge = parseJudgeResponse(responseText);
+    return {
+      passed: judge.passed,
+      score: judge.score / 100,
+      // Normalize to 0–1.
+      reasoning: judge.reasoning
+    };
+  }
+  async verify(context) {
+    const formatCheck = await this.checkFormat(context);
+    let semanticCheck;
+    if (!this.skipSemanticOnFormatFailure || formatCheck.passed) {
+      try {
+        semanticCheck = await this.checkSemantic(context);
+      } catch (err) {
+        semanticCheck = {
+          passed: false,
+          score: 0,
+          reasoning: `Semantic check failed: ${err instanceof Error ? err.message : String(err)}`
+        };
+      }
+    }
+    const issues = [];
+    if (!formatCheck.passed && formatCheck.errors) {
+      for (const error of formatCheck.errors) {
+        issues.push({ severity: "error", message: error });
+      }
+    }
+    if (semanticCheck && !semanticCheck.passed) {
+      issues.push({
+        severity: "error",
+        message: `Semantic check: ${semanticCheck.reasoning}`
+      });
+    }
+    let outcome;
+    let confidence;
+    if (!formatCheck.passed) {
+      outcome = "failure";
+      confidence = 0.2;
+    } else if (semanticCheck) {
+      if (semanticCheck.score >= 0.71) {
+        outcome = "success";
+        confidence = semanticCheck.score;
+      } else if (semanticCheck.score >= 0.31) {
+        outcome = "partial";
+        confidence = semanticCheck.score;
+      } else {
+        outcome = "failure";
+        confidence = semanticCheck.score;
+      }
+    } else {
+      outcome = formatCheck.passed ? "success" : "failure";
+      confidence = formatCheck.passed ? 0.7 : 0.2;
+    }
+    const suggestions = [];
+    if (!formatCheck.passed) {
+      suggestions.push("Fix format issues before attempting semantic verification.");
+    }
+    if (semanticCheck && !semanticCheck.passed) {
+      suggestions.push(`Semantic assessment: ${semanticCheck.reasoning}`);
+    }
+    return {
+      outcome,
+      confidence,
+      reasoning: semanticCheck ? `Format: ${formatCheck.passed ? "PASS" : "FAIL"} | Semantic: ${semanticCheck.passed ? "PASS" : "FAIL"} (score: ${(semanticCheck.score * 100).toFixed(0)}%)` : `Format: ${formatCheck.passed ? "PASS" : "FAIL"} | Semantic: SKIPPED`,
+      issues: issues.length > 0 ? issues : void 0,
+      suggestions: suggestions.length > 0 ? suggestions : void 0,
+      formatCheck,
+      semanticCheck
+    };
+  }
+};
+function createAutoRecallHook(backend, opts) {
+  const maxResults = opts?.maxResults ?? 5;
+  const minScore = opts?.minScore ?? 0.1;
+  return async (ctx) => {
+    const messages = ctx.getMessages();
+    const lastUserMsg = messages.filter((m) => m.role === "user").pop();
+    if (!lastUserMsg || typeof lastUserMsg.content !== "string") return;
+    const query = lastUserMsg.content;
+    if (!query.trim()) return;
+    const results = await backend.recall(query, {
+      limit: maxResults,
+      minScore,
+      ...opts?.recallOpts,
+      ...opts?.namespace ? { keyPrefix: `${opts.namespace}:` } : {}
+    });
+    if (results.length === 0) return;
+    const memoryLines = results.map(
+      (r, i) => `${i + 1}. [${r.matchType}, score=${r.score.toFixed(2)}] ${r.content}`
+    );
+    const memoryText = "Relevant memories from previous conversations:\n" + memoryLines.join("\n") + "\n\nUse these memories to provide more personalized and context-aware responses.";
+    await ctx.addMessage({ role: "system", content: memoryText });
+  };
+}
+function createAutoSummarizeHook(backend, opts) {
+  const minMessages = opts?.minMessages ?? 1;
+  const maxLength = opts?.maxSummaryLength ?? 2e3;
+  return async (ctx, answer) => {
+    const messages = ctx.getMessages();
+    const userMessages = messages.filter((m) => m.role === "user");
+    if (userMessages.length < minMessages) return;
+    if (!answer || answer.trim().length < 10) return;
+    const userQueries = userMessages.map((m) => typeof m.content === "string" ? m.content : "").filter(Boolean);
+    const summaryParts = [
+      `User asked: ${userQueries.join(" \u2192 ")}`,
+      `Assistant answered: ${answer}`
+    ];
+    let summary = summaryParts.join("\n");
+    if (summary.length > maxLength) {
+      summary = summary.slice(0, maxLength - 3) + "...";
+    }
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const queryPrefix = userQueries[0]?.slice(0, 50).replace(/[^a-zA-Z0-9 ]/g, "") ?? "conversation";
+    const nsPrefix = opts?.namespace ? `${opts.namespace}:` : "";
+    const key = `${nsPrefix}conv:${timestamp}:${queryPrefix}`;
+    await backend.store(key, summary, {
+      type: "conversation_summary",
+      timestamp,
+      messageCount: messages.length,
+      userMessageCount: userMessages.length
+    });
+  };
+}
+
+export {
+  SteeringQueue,
+  NAMED_STRATEGIES,
+  ContextManager,
+  ToolWorkerPool,
+  Session,
+  AgentLoop,
+  FormatVerifier,
+  LLMVerifier,
+  createAutoRecallHook,
+  createAutoSummarizeHook
+};