@mastra/core 1.4.0 → 1.5.0-alpha.1

package/dist/harness/index.js

@@ -0,0 +1,1723 @@
+import { Agent } from '../chunk-A7V2NSY3.js';
+import { Workspace } from '../chunk-FZ5DRHKE.js';
+import { createTool } from '../chunk-BQHWJLXU.js';
+import { RequestContext } from '../chunk-CCLV5CAA.js';
+import { z } from 'zod';
+
+var questionCounter = 0;
+var planCounter = 0;
+var askUserTool = createTool({
+  id: "ask_user",
+  description: "Ask the user a question and wait for their response. Use this when you need clarification, want to validate assumptions, or need the user to make a decision between options. Provide options for structured choices (2-4 options), or omit them for open-ended questions.",
+  inputSchema: z.object({
+    question: z.string().min(1).describe("The question to ask the user. Should be clear and specific."),
+    options: z.array(
+      z.object({
+        label: z.string().describe("Short display text for this option (1-5 words)"),
+        description: z.string().optional().describe("Explanation of what this option means")
+      })
+    ).optional().describe("Optional choices. If provided, shows a selection list. If omitted, shows a free-text input.")
+  }),
+  execute: async ({ question, options }, context) => {
+    try {
+      const harnessCtx = context?.requestContext?.get("harness");
+      if (!harnessCtx?.emitEvent || !harnessCtx?.registerQuestion) {
+        return {
+          content: `[Question for user]: ${question}${options ? "\nOptions: " + options.map((o) => o.label).join(", ") : ""}`,
+          isError: false
+        };
+      }
+      const questionId = `q_${++questionCounter}_${Date.now()}`;
+      const answer = await new Promise((resolve, reject) => {
+        const signal = harnessCtx.abortSignal;
+        if (signal?.aborted) {
+          reject(new DOMException("Aborted", "AbortError"));
+          return;
+        }
+        const onAbort = () => reject(new DOMException("Aborted", "AbortError"));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        harnessCtx.registerQuestion(questionId, (answer2) => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve(answer2);
+        });
+        harnessCtx.emitEvent({
+          type: "ask_question",
+          questionId,
+          question,
+          options
+        });
+      });
+      return { content: `User answered: ${answer}`, isError: false };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : "Unknown error";
+      return { content: `Failed to ask user: ${msg}`, isError: true };
+    }
+  }
+});
+var submitPlanTool = createTool({
+  id: "submit_plan",
+  description: "Submit a completed implementation plan for user review. The plan will be rendered as markdown and the user can approve, reject, or request changes. Use this when your exploration is complete and you have a concrete plan ready for review. On approval, the system automatically switches to the default mode so you can implement.",
+  inputSchema: z.object({
+    title: z.string().optional().describe("Short title for the plan (e.g., 'Add dark mode toggle')"),
+    plan: z.string().min(1).describe("The full plan content in markdown format. Should include Overview, Steps, and Verification sections.")
+  }),
+  execute: async ({ title, plan }, context) => {
+    try {
+      const harnessCtx = context?.requestContext?.get("harness");
+      if (!harnessCtx?.emitEvent || !harnessCtx?.registerPlanApproval) {
+        return {
+          content: `[Plan submitted for review]
+
+Title: ${title || "Implementation Plan"}
+
+${plan}`,
+          isError: false
+        };
+      }
+      const planId = `plan_${++planCounter}_${Date.now()}`;
+      const result = await new Promise((resolve, reject) => {
+        const signal = harnessCtx.abortSignal;
+        if (signal?.aborted) {
+          reject(new DOMException("Aborted", "AbortError"));
+          return;
+        }
+        const onAbort = () => reject(new DOMException("Aborted", "AbortError"));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        harnessCtx.registerPlanApproval(planId, (res) => {
+          signal?.removeEventListener("abort", onAbort);
+          resolve(res);
+        });
+        harnessCtx.emitEvent({
+          type: "plan_approval_required",
+          planId,
+          title: title || "Implementation Plan",
+          plan
+        });
+      });
+      if (result.action === "approved") {
+        return {
+          content: "Plan approved. Proceed with implementation following the approved plan.",
+          isError: false
+        };
+      }
+      const feedback = result.feedback ? `
+
+User feedback: ${result.feedback}` : "";
+      return {
+        content: `Plan was not approved. The user wants revisions.${feedback}
+
+Please revise the plan based on the feedback and submit again with submit_plan.`,
+        isError: false
+      };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : "Unknown error";
+      return { content: `Failed to submit plan: ${msg}`, isError: true };
+    }
+  }
+});
+function createSubagentTool(opts) {
+  const { subagents, resolveModel, harnessTools, fallbackModelId } = opts;
+  const subagentIds = subagents.map((s) => s.id);
+  const typeDescriptions = subagents.map((s) => `- **${s.id}** (${s.name}): ${s.description}`).join("\n");
+  return createTool({
+    id: "subagent",
+    description: `Delegate a focused task to a specialized subagent. The subagent runs independently with a constrained toolset, then returns its findings as text.
+
+Available agent types:
+${typeDescriptions}
+
+The subagent runs in its own context \u2014 it does NOT see the parent conversation history. Write a clear, self-contained task description.
+
+Use this tool when:
+- You want to run multiple investigations in parallel
+- The task is self-contained and can be delegated`,
+    inputSchema: z.object({
+      agentType: z.enum(subagentIds).describe("Type of subagent to spawn"),
+      task: z.string().describe(
+        "Clear, self-contained description of what the subagent should do. Include all relevant context \u2014 the subagent cannot see the parent conversation."
+      ),
+      modelId: z.string().optional().describe("Optional model ID override for this task.")
+    }),
+    execute: async ({ agentType, task, modelId }, context) => {
+      const definition = subagents.find((s) => s.id === agentType);
+      if (!definition) {
+        return {
+          content: `Unknown agent type: ${agentType}. Valid types: ${subagentIds.join(", ")}`,
+          isError: true
+        };
+      }
+      const harnessCtx = context?.requestContext?.get("harness");
+      const emitEvent = harnessCtx?.emitEvent;
+      const abortSignal = harnessCtx?.abortSignal;
+      const toolCallId = context?.agent?.toolCallId ?? "unknown";
+      const mergedTools = { ...definition.tools };
+      if (definition.allowedHarnessTools && harnessTools) {
+        for (const toolId of definition.allowedHarnessTools) {
+          if (harnessTools[toolId] && !mergedTools[toolId]) {
+            mergedTools[toolId] = harnessTools[toolId];
+          }
+        }
+      }
+      const harnessModelId = harnessCtx?.getSubagentModelId?.(agentType) ?? void 0;
+      const resolvedModelId = modelId ?? harnessModelId ?? definition.defaultModelId ?? fallbackModelId;
+      if (!resolvedModelId) {
+        return { content: "No model ID available for subagent. Configure defaultModelId.", isError: true };
+      }
+      let model;
+      try {
+        model = resolveModel(resolvedModelId);
+      } catch (err) {
+        return {
+          content: `Failed to resolve model "${resolvedModelId}": ${err instanceof Error ? err.message : String(err)}`,
+          isError: true
+        };
+      }
+      const subagent = new Agent({
+        id: `subagent-${definition.id}`,
+        name: `${definition.name} Subagent`,
+        instructions: definition.instructions,
+        model,
+        tools: mergedTools
+      });
+      const startTime = Date.now();
+      emitEvent?.({
+        type: "subagent_start",
+        toolCallId,
+        agentType,
+        task,
+        modelId: resolvedModelId
+      });
+      let partialText = "";
+      const toolCallLog = [];
+      try {
+        const response = await subagent.stream(task, {
+          maxSteps: 50,
+          abortSignal,
+          requireToolApproval: false
+        });
+        for await (const chunk of response.fullStream) {
+          switch (chunk.type) {
+            case "text-delta":
+              partialText += chunk.payload.text;
+              emitEvent?.({
+                type: "subagent_text_delta",
+                toolCallId,
+                agentType,
+                textDelta: chunk.payload.text
+              });
+              break;
+            case "tool-call":
+              toolCallLog.push({ name: chunk.payload.toolName, toolCallId: chunk.payload.toolCallId });
+              emitEvent?.({
+                type: "subagent_tool_start",
+                toolCallId,
+                agentType,
+                subToolName: chunk.payload.toolName,
+                subToolArgs: chunk.payload.args
+              });
+              break;
+            case "tool-result": {
+              const isErr = chunk.payload.isError ?? false;
+              for (let i = toolCallLog.length - 1; i >= 0; i--) {
+                if (toolCallLog[i].toolCallId === chunk.payload.toolCallId && toolCallLog[i].isError === void 0) {
+                  toolCallLog[i].isError = isErr;
+                  break;
+                }
+              }
+              emitEvent?.({
+                type: "subagent_tool_end",
+                toolCallId,
+                agentType,
+                subToolName: chunk.payload.toolName,
+                subToolResult: chunk.payload.result,
+                isError: isErr
+              });
+              break;
+            }
+          }
+        }
+        if (abortSignal?.aborted) {
+          const durationMs2 = Date.now() - startTime;
+          const abortResult = partialText ? `[Aborted by user]
+
+Partial output:
+${partialText}` : "[Aborted by user]";
+          emitEvent?.({ type: "subagent_end", toolCallId, agentType, result: abortResult, isError: false, durationMs: durationMs2 });
+          const meta2 = buildSubagentMeta(resolvedModelId, durationMs2, toolCallLog);
+          return { content: abortResult + meta2, isError: false };
+        }
+        const fullOutput = await response.getFullOutput();
+        const resultText = fullOutput.text || partialText;
+        const durationMs = Date.now() - startTime;
+        emitEvent?.({ type: "subagent_end", toolCallId, agentType, result: resultText, isError: false, durationMs });
+        const meta = buildSubagentMeta(resolvedModelId, durationMs, toolCallLog);
+        return { content: resultText + meta, isError: false };
+      } catch (err) {
+        const isAbort = err instanceof Error && (err.name === "AbortError" || err.message?.includes("abort") || err.message?.includes("cancel"));
+        const durationMs = Date.now() - startTime;
+        if (isAbort) {
+          const abortResult = partialText ? `[Aborted by user]
+
+Partial output:
+${partialText}` : "[Aborted by user]";
+          emitEvent?.({ type: "subagent_end", toolCallId, agentType, result: abortResult, isError: false, durationMs });
+          const meta2 = buildSubagentMeta(resolvedModelId, durationMs, toolCallLog);
+          return { content: abortResult + meta2, isError: false };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        emitEvent?.({ type: "subagent_end", toolCallId, agentType, result: message, isError: true, durationMs });
+        const meta = buildSubagentMeta(resolvedModelId, durationMs, toolCallLog);
+        return { content: `Subagent "${definition.name}" failed: ${message}` + meta, isError: true };
+      }
+    }
+  });
+}
+function buildSubagentMeta(modelId, durationMs, toolCalls) {
+  const tools = toolCalls.map((tc) => `${tc.name}:${tc.isError ? "err" : "ok"}`).join(",");
+  return `
+<subagent-meta modelId="${modelId}" durationMs="${durationMs}" tools="${tools}" />`;
+}
+function parseSubagentMeta(content) {
+  const match = content.match(/\n<subagent-meta modelId="([^"]*)" durationMs="(\d+)" tools="([^"]*)" \/>$/);
+  if (!match) return { text: content };
+  const text = content.slice(0, match.index);
+  const modelId = match[1];
+  const durationMs = parseInt(match[2], 10);
+  const toolCalls = match[3] ? match[3].split(",").filter(Boolean).map((entry) => {
+    const [name, status] = entry.split(":");
+    return { name, isError: status === "err" };
+  }) : [];
+  return { text, modelId, durationMs, toolCalls };
+}
+
+// src/harness/harness.ts
+var Harness = class {
+  id;
+  config;
+  state;
+  currentModeId;
+  currentThreadId = null;
+  resourceId;
+  listeners = [];
+  abortController = null;
+  abortRequested = false;
+  currentRunId = null;
+  currentOperationId = 0;
+  followUpQueue = [];
+  pendingApprovalResolve = null;
+  pendingApprovalToolName = null;
+  pendingQuestions = /* @__PURE__ */ new Map();
+  pendingPlanApprovals = /* @__PURE__ */ new Map();
+  workspace = void 0;
+  workspaceFn = void 0;
+  workspaceInitialized = false;
+  heartbeatTimers = /* @__PURE__ */ new Map();
+  tokenUsage = {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0
+  };
+  sessionGrantedCategories = /* @__PURE__ */ new Set();
+  sessionGrantedTools = /* @__PURE__ */ new Set();
+  constructor(config) {
+    this.id = config.id;
+    this.config = config;
+    this.resourceId = config.resourceId ?? config.id;
+    this.state = {
+      ...this.getSchemaDefaults(),
+      ...config.initialState
+    };
+    const defaultMode = config.modes.find((m) => m.default) ?? config.modes[0];
+    if (!defaultMode) {
+      throw new Error("Harness requires at least one agent mode");
+    }
+    this.currentModeId = defaultMode.id;
+    if (config.workspace instanceof Workspace) {
+      this.workspace = config.workspace;
+    } else if (typeof config.workspace === "function") {
+      this.workspaceFn = config.workspace;
+    }
+    const currentModel = this.state.currentModelId;
+    if (!currentModel && defaultMode.defaultModelId) {
+      void this.setState({ currentModelId: defaultMode.defaultModelId });
+    }
+  }
+  // ===========================================================================
+  // Initialization
+  // ===========================================================================
+  /**
+   * Initialize the harness — loads storage and workspace.
+   * Must be called before using the harness.
+   */
+  async init() {
+    if (this.config.storage) {
+      await this.config.storage.init();
+    }
+    if (this.config.workspace && !this.workspaceInitialized && !this.workspaceFn) {
+      try {
+        if (!this.workspace) {
+          this.workspace = new Workspace(this.config.workspace);
+        }
+        this.emit({ type: "workspace_status_changed", status: "initializing" });
+        await this.workspace.init();
+        this.workspaceInitialized = true;
+        this.emit({ type: "workspace_status_changed", status: "ready" });
+        this.emit({
+          type: "workspace_ready",
+          workspaceId: this.workspace.id,
+          workspaceName: this.workspace.name
+        });
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.workspace = void 0;
+        this.workspaceInitialized = false;
+        this.emit({ type: "workspace_status_changed", status: "error", error: err });
+        this.emit({ type: "workspace_error", error: err });
+      }
+    }
+    const workspaceForAgents = this.workspaceFn ?? this.workspace;
+    for (const mode of this.config.modes) {
+      const agent = typeof mode.agent === "function" ? null : mode.agent;
+      if (!agent) continue;
+      if (this.config.memory && !agent.hasOwnMemory()) {
+        agent.__setMemory(this.config.memory);
+      }
+      if (workspaceForAgents && !agent.hasOwnWorkspace()) {
+        agent.__setWorkspace(workspaceForAgents);
+      }
+    }
+    this.startHeartbeats();
+  }
+  /**
+   * Select the most recent thread, or create one if none exist.
+   */
+  async selectOrCreateThread() {
+    const threads = await this.listThreads();
+    if (threads.length === 0) {
+      return await this.createThread();
+    }
+    const sortedThreads = [...threads].sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+    const mostRecent = sortedThreads[0];
+    this.currentThreadId = mostRecent.id;
+    await this.loadThreadMetadata();
+    return mostRecent;
+  }
+  async getMemoryStorage() {
+    if (!this.config.storage) {
+      throw new Error("Storage is not configured on this Harness");
+    }
+    const memoryStorage = await this.config.storage.getStore("memory");
+    if (!memoryStorage) {
+      throw new Error("Storage does not have a memory domain configured");
+    }
+    return memoryStorage;
+  }
+  // ===========================================================================
+  // State Management
+  // ===========================================================================
+  /**
+   * Get current harness state (read-only snapshot).
+   */
+  getState() {
+    return { ...this.state };
+  }
+  /**
+   * Update harness state. Validates against schema if provided.
+   * Emits state_changed event.
+   */
+  async setState(updates) {
+    const changedKeys = Object.keys(updates);
+    const newState = { ...this.state, ...updates };
+    if (this.config.stateSchema) {
+      const result = this.config.stateSchema.safeParse(newState);
+      if (!result.success) {
+        throw new Error(`Invalid state update: ${result.error.message}`);
+      }
+      this.state = result.data;
+    } else {
+      this.state = newState;
+    }
+    this.emit({ type: "state_changed", state: this.state, changedKeys });
+  }
+  getSchemaDefaults() {
+    if (!this.config.stateSchema) return {};
+    const shape = this.config.stateSchema.shape;
+    const defaults = {};
+    for (const [key, field] of Object.entries(shape)) {
+      try {
+        const result = field.safeParse(void 0);
+        if (result.success && result.data !== void 0) {
+          defaults[key] = result.data;
+        }
+      } catch {
+      }
+    }
+    return defaults;
+  }
+  // ===========================================================================
+  // Mode Management
+  // ===========================================================================
+  getModes() {
+    return this.config.modes;
+  }
+  getCurrentModeId() {
+    return this.currentModeId;
+  }
+  getCurrentMode() {
+    const mode = this.config.modes.find((m) => m.id === this.currentModeId);
+    if (!mode) {
+      throw new Error(`Mode not found: ${this.currentModeId}`);
+    }
+    return mode;
+  }
+  /**
+   * Switch to a different mode.
+   * Aborts any in-progress generation and switches to the mode's default model.
+   */
+  async switchMode(modeId) {
+    const mode = this.config.modes.find((m) => m.id === modeId);
+    if (!mode) {
+      throw new Error(`Mode not found: ${modeId}`);
+    }
+    this.abort();
+    const currentModelId = this.getCurrentModelId();
+    if (currentModelId) {
+      await this.persistThreadSetting(`modeModelId_${this.currentModeId}`, currentModelId);
+    }
+    const previousModeId = this.currentModeId;
+    this.currentModeId = modeId;
+    await this.persistThreadSetting("currentModeId", modeId);
+    const modeModelId = await this.loadModeModelId(modeId);
+    if (modeModelId) {
+      void this.setState({ currentModelId: modeModelId });
+      this.emit({ type: "model_changed", modelId: modeModelId });
+    }
+    this.emit({ type: "mode_changed", modeId, previousModeId });
+  }
+  /**
+   * Load the stored model ID for a specific mode.
+   * Falls back to: thread metadata -> mode's defaultModelId -> current model.
+   */
+  async loadModeModelId(modeId) {
+    if (this.currentThreadId && this.config.storage) {
+      try {
+        const memoryStorage = await this.getMemoryStorage();
+        const thread = await memoryStorage.getThreadById({ threadId: this.currentThreadId });
+        const meta = thread?.metadata;
+        const stored = meta?.[`modeModelId_${modeId}`];
+        if (stored) return stored;
+      } catch {
+      }
+    }
+    const mode = this.config.modes.find((m) => m.id === modeId);
+    if (mode?.defaultModelId) return mode.defaultModelId;
+    return null;
+  }
+  /**
+   * Get the agent for the current mode.
+   */
+  getCurrentAgent() {
+    const mode = this.getCurrentMode();
+    if (typeof mode.agent === "function") {
+      return mode.agent(this.state);
+    }
+    return mode.agent;
+  }
+  /**
+   * Get a short display name from the current model ID.
+   */
+  getModelName() {
+    const modelId = this.getCurrentModelId();
+    if (!modelId || modelId === "unknown") return modelId || "unknown";
+    const parts = modelId.split("/");
+    return parts[parts.length - 1] || modelId;
+  }
+  /**
+   * Get the full model ID (e.g., "anthropic/claude-sonnet-4").
+   */
+  getFullModelId() {
+    return this.getCurrentModelId();
+  }
+  /**
+   * Switch to a different model at runtime.
+   */
+  async switchModel(modelId, scope = "thread", modeId) {
+    const targetModeId = modeId ?? this.currentModeId;
+    if (targetModeId === this.currentModeId) {
+      void this.setState({ currentModelId: modelId });
+    }
+    if (scope === "thread") {
+      await this.persistThreadSetting(`modeModelId_${targetModeId}`, modelId);
+    }
+    this.emit({ type: "model_changed", modelId, scope, modeId: targetModeId });
+  }
+  getCurrentModelId() {
+    const state = this.getState();
+    return state.currentModelId ?? "";
+  }
+  hasModelSelected() {
+    return this.getCurrentModelId() !== "";
+  }
+  /**
+   * Check if the current model's provider has authentication configured.
+   * Uses the provider registry's `apiKeyEnvVar` and the optional `modelAuthChecker` hook.
+   */
+  async getCurrentModelAuthStatus() {
+    const modelId = this.getCurrentModelId();
+    const provider = modelId.split("/")[0];
+    if (!provider) return { hasAuth: true };
+    if (this.config.modelAuthChecker) {
+      const result = this.config.modelAuthChecker(provider);
+      if (result === true) return { hasAuth: true };
+      if (result === false) {
+        const apiKeyEnvVar = await this.getProviderApiKeyEnvVar(provider);
+        return { hasAuth: false, apiKeyEnvVar };
+      }
+    }
+    try {
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-VEJ3PN4S.js');
+      const registry = PROVIDER_REGISTRY;
+      const providerConfig = registry[provider];
+      const envVars = providerConfig?.apiKeyEnvVar;
+      const apiKeyEnvVar = Array.isArray(envVars) ? envVars[0] : envVars;
+      if (apiKeyEnvVar && process.env[apiKeyEnvVar]) {
+        return { hasAuth: true };
+      }
+      return { hasAuth: false, apiKeyEnvVar: apiKeyEnvVar || void 0 };
+    } catch {
+      return { hasAuth: true };
+    }
+  }
+  /**
+   * Get all available models from the provider registry with auth status.
+   * Uses the optional `modelAuthChecker` and `modelUseCountProvider` hooks.
+   */
+  async getAvailableModels() {
+    try {
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-VEJ3PN4S.js');
+      if (!PROVIDER_REGISTRY) return [];
+      const registry = PROVIDER_REGISTRY;
+      const providers = Object.keys(registry);
+      const useCounts = this.config.modelUseCountProvider?.() ?? {};
+      const models = [];
+      for (const provider of providers) {
+        const providerConfig = registry[provider];
+        const envVars = providerConfig?.apiKeyEnvVar;
+        const apiKeyEnvVar = Array.isArray(envVars) ? envVars[0] : envVars;
+        const hasEnvKey = apiKeyEnvVar ? !!process.env[apiKeyEnvVar] : false;
+        let hasApiKey = hasEnvKey;
+        if (!hasApiKey && this.config.modelAuthChecker) {
+          const customAuth = this.config.modelAuthChecker(provider);
+          if (customAuth === true) hasApiKey = true;
+        }
+        if (providerConfig?.models && Array.isArray(providerConfig.models)) {
+          for (const modelName of providerConfig.models) {
+            const id = `${provider}/${modelName}`;
+            models.push({
+              id,
+              provider,
+              modelName,
+              hasApiKey,
+              apiKeyEnvVar: apiKeyEnvVar || void 0,
+              useCount: useCounts[id] ?? 0
+            });
+          }
+        }
+      }
+      return models;
+    } catch (error) {
+      console.warn("Failed to load available models:", error);
+      return [];
+    }
+  }
+  async getProviderApiKeyEnvVar(provider) {
+    try {
+      const { PROVIDER_REGISTRY } = await import('../provider-registry-VEJ3PN4S.js');
+      const registry = PROVIDER_REGISTRY;
+      const envVars = registry[provider]?.apiKeyEnvVar;
+      return Array.isArray(envVars) ? envVars[0] : envVars;
+    } catch {
+      return void 0;
+    }
+  }
+  // ===========================================================================
+  // Thread Management
+  // ===========================================================================
+  getCurrentThreadId() {
+    return this.currentThreadId;
+  }
+  getResourceId() {
+    return this.resourceId;
+  }
+  setResourceId(resourceId) {
+    this.resourceId = resourceId;
+    this.currentThreadId = null;
+  }
+  async createThread(title) {
+    const now = /* @__PURE__ */ new Date();
+    const thread = {
+      id: this.generateId(),
+      resourceId: this.resourceId,
+      title: title || "New Thread",
+      createdAt: now,
+      updatedAt: now
+    };
+    const currentStateModel = this.state.currentModelId;
+    const currentMode = this.getCurrentMode();
+    const modelId = currentStateModel || currentMode.defaultModelId;
+    const metadata = {};
+    if (modelId) {
+      metadata.currentModelId = modelId;
+      metadata[`modeModelId_${this.currentModeId}`] = modelId;
+    }
+    if (this.config.storage) {
+      const memoryStorage = await this.getMemoryStorage();
+      await memoryStorage.saveThread({
+        thread: {
+          id: thread.id,
+          resourceId: thread.resourceId,
+          title: thread.title,
+          createdAt: thread.createdAt,
+          updatedAt: thread.updatedAt,
+          metadata: Object.keys(metadata).length > 0 ? metadata : void 0
+        }
+      });
+    }
+    this.currentThreadId = thread.id;
+    if (modelId && !currentStateModel) {
+      void this.setState({ currentModelId: modelId });
+    }
+    this.tokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    this.emit({ type: "thread_created", thread });
+    return thread;
+  }
+  async renameThread(title) {
+    if (!this.currentThreadId || !this.config.storage) return;
+    const memoryStorage = await this.getMemoryStorage();
+    const thread = await memoryStorage.getThreadById({ threadId: this.currentThreadId });
+    if (thread) {
+      await memoryStorage.saveThread({
+        thread: { ...thread, title, updatedAt: /* @__PURE__ */ new Date() }
+      });
+    }
+  }
+  async switchThread(threadId) {
+    this.abort();
+    if (this.config.storage) {
+      const memoryStorage = await this.getMemoryStorage();
+      const thread = await memoryStorage.getThreadById({ threadId });
+      if (!thread) {
+        throw new Error(`Thread not found: ${threadId}`);
+      }
+    }
+    const previousThreadId = this.currentThreadId;
+    this.currentThreadId = threadId;
+    await this.loadThreadMetadata();
+    this.emit({ type: "thread_changed", threadId, previousThreadId });
+  }
+  async listThreads(options) {
+    if (!this.config.storage) return [];
+    const memoryStorage = await this.getMemoryStorage();
+    const filter = options?.allResources ? void 0 : { resourceId: this.resourceId };
+    const result = await memoryStorage.listThreads({ filter });
+    return result.threads.map((thread) => ({
+      id: thread.id,
+      resourceId: thread.resourceId,
+      title: thread.title,
+      createdAt: thread.createdAt,
+      updatedAt: thread.updatedAt,
+      metadata: thread.metadata
+    }));
+  }
+  async persistThreadSetting(key, value) {
+    if (!this.currentThreadId || !this.config.storage) return;
+    try {
+      const memoryStorage = await this.getMemoryStorage();
+      const thread = await memoryStorage.getThreadById({ threadId: this.currentThreadId });
+      if (thread) {
+        await memoryStorage.saveThread({
+          thread: {
+            ...thread,
+            metadata: { ...thread.metadata, [key]: value },
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        });
+      }
+    } catch {
+    }
+  }
+  async removeThreadSetting(key) {
+    if (!this.currentThreadId || !this.config.storage) return;
+    try {
+      const memoryStorage = await this.getMemoryStorage();
+      const thread = await memoryStorage.getThreadById({ threadId: this.currentThreadId });
+      if (thread && thread.metadata) {
+        const metadata = { ...thread.metadata };
+        delete metadata[key];
+        await memoryStorage.saveThread({
+          thread: {
+            ...thread,
+            metadata: Object.keys(metadata).length > 0 ? metadata : void 0,
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        });
+      }
+    } catch {
+    }
+  }
+  async loadThreadMetadata() {
+    if (!this.currentThreadId || !this.config.storage) {
+      this.tokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+      return;
+    }
+    try {
+      const memoryStorage = await this.getMemoryStorage();
+      const thread = await memoryStorage.getThreadById({ threadId: this.currentThreadId });
+      const savedUsage = thread?.metadata?.tokenUsage;
+      if (savedUsage) {
+        this.tokenUsage = {
+          promptTokens: savedUsage.promptTokens ?? 0,
+          completionTokens: savedUsage.completionTokens ?? 0,
+          totalTokens: savedUsage.totalTokens ?? 0
+        };
+      } else {
+        this.tokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+      }
+      const meta = thread?.metadata;
+      const updates = {};
+      const modeModelKey = `modeModelId_${this.currentModeId}`;
+      if (meta?.[modeModelKey]) {
+        updates.currentModelId = meta[modeModelKey];
+      } else if (meta?.currentModelId) {
+        updates.currentModelId = meta.currentModelId;
+      }
+      if (meta?.currentModeId) {
+        const savedModeId = meta.currentModeId;
+        const modeExists = this.config.modes.some((m) => m.id === savedModeId);
+        if (modeExists && savedModeId !== this.currentModeId) {
+          this.currentModeId = savedModeId;
+          const restoredModeModelKey = `modeModelId_${savedModeId}`;
+          if (meta[restoredModeModelKey]) {
+            updates.currentModelId = meta[restoredModeModelKey];
+          }
+          this.emit({
+            type: "mode_changed",
+            modeId: savedModeId,
+            previousModeId: this.config.modes.find((m) => m.default)?.id || this.config.modes[0].id
+          });
+        }
+      }
+      if (Object.keys(updates).length > 0) {
+        void this.setState(updates);
+      }
+    } catch {
+      this.tokenUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    }
+  }
+  // ===========================================================================
+  // Observational Memory
+  // ===========================================================================
+  /**
+   * Load observational memory progress for the current thread.
+   * Reads the OM record and recent messages to reconstruct status,
+   * then emits an `om_status` event for the UI.
+   */
+  async loadOMProgress() {
+    if (!this.currentThreadId) return;
+    try {
+      const memoryStorage = await this.getMemoryStorage();
+      const record = await memoryStorage.getObservationalMemory(this.currentThreadId, this.resourceId);
+      if (!record) return;
+      const config = record.config;
+      const getThreshold = (val, fallback) => {
+        if (!val) return fallback;
+        if (typeof val === "number") return val;
+        return val.max;
+      };
+      let observationThreshold = getThreshold(config?.observationThreshold, 3e4);
+      let reflectionThreshold = getThreshold(config?.reflectionThreshold, 4e4);
+      let messageTokens = record.pendingMessageTokens ?? 0;
+      let observationTokens = record.observationTokenCount ?? 0;
+      let bufferedObs = {
+        status: "idle",
+        chunks: 0,
+        messageTokens: 0,
+        projectedMessageRemoval: 0,
+        observationTokens: 0
+      };
+      let bufferedRef = {
+        status: "idle",
+        inputObservationTokens: 0,
+        observationTokens: 0
+      };
+      let generationCount = 0;
+      let stepNumber = 0;
+      const messagesResult = await memoryStorage.listMessages({
+        threadId: this.currentThreadId,
+        perPage: 70,
+        page: 0,
+        orderBy: { field: "createdAt", direction: "DESC" }
+      });
+      const messages = messagesResult.messages;
+      let foundStatus = false;
+      for (const msg of messages) {
+        if (msg.role !== "assistant") continue;
+        const content = msg.content;
+        if (typeof content === "string" || !content?.parts) continue;
+        for (let i = content.parts.length - 1; i >= 0; i--) {
+          const part = content.parts[i];
+          if (part.type === "data-om-status" && part.data?.windows) {
+            const w = part.data.windows;
+            messageTokens = w.active?.messages?.tokens ?? messageTokens;
+            observationTokens = w.active?.observations?.tokens ?? observationTokens;
+            const msgThresh = w.active?.messages?.threshold;
+            const obsThresh = w.active?.observations?.threshold;
+            if (msgThresh) observationThreshold = msgThresh;
+            if (obsThresh) reflectionThreshold = obsThresh;
+            const bo = w.buffered?.observations;
+            if (bo) {
+              bufferedObs = {
+                status: bo.status ?? "idle",
+                chunks: bo.chunks ?? 0,
+                messageTokens: bo.messageTokens ?? 0,
+                projectedMessageRemoval: bo.projectedMessageRemoval ?? 0,
+                observationTokens: bo.observationTokens ?? 0
+              };
+            }
+            const br = w.buffered?.reflection;
+            if (br) {
+              bufferedRef = {
+                status: br.status ?? "idle",
+                inputObservationTokens: br.inputObservationTokens ?? 0,
+                observationTokens: br.observationTokens ?? 0
+              };
+            }
+            generationCount = part.data.generationCount ?? 0;
+            stepNumber = part.data.stepNumber ?? 0;
+            foundStatus = true;
+            break;
+          }
+        }
+        if (foundStatus) break;
+      }
+      this.emit({
+        type: "om_status",
+        windows: {
+          active: {
+            messages: { tokens: messageTokens, threshold: observationThreshold },
+            observations: { tokens: observationTokens, threshold: reflectionThreshold }
+          },
+          buffered: { observations: bufferedObs, reflection: bufferedRef }
+        },
+        recordId: record.id ?? "",
+        threadId: this.currentThreadId,
+        stepNumber,
+        generationCount
+      });
+    } catch {
+    }
+  }
+  /**
+   * Returns the observer model ID from state, falling back to omConfig defaults.
+   */
+  getObserverModelId() {
+    return this.state.observerModelId ?? this.config.omConfig?.defaultObserverModelId;
+  }
+  /**
+   * Returns the reflector model ID from state, falling back to omConfig defaults.
+   */
+  getReflectorModelId() {
+    return this.state.reflectorModelId ?? this.config.omConfig?.defaultReflectorModelId;
+  }
+  /**
+   * Returns the observation threshold from state, falling back to omConfig defaults.
+   */
+  getObservationThreshold() {
+    return this.state.observationThreshold ?? this.config.omConfig?.defaultObservationThreshold;
+  }
+  /**
+   * Returns the reflection threshold from state, falling back to omConfig defaults.
+   */
+  getReflectionThreshold() {
+    return this.state.reflectionThreshold ?? this.config.omConfig?.defaultReflectionThreshold;
+  }
+  /**
+   * Resolves the observer model ID to a language model instance via `resolveModel`.
+   */
+  getResolvedObserverModel() {
+    const modelId = this.getObserverModelId();
+    if (!modelId || !this.config.resolveModel) return void 0;
+    return this.config.resolveModel(modelId);
+  }
+  /**
+   * Resolves the reflector model ID to a language model instance via `resolveModel`.
+   */
+  getResolvedReflectorModel() {
+    const modelId = this.getReflectorModelId();
+    if (!modelId || !this.config.resolveModel) return void 0;
+    return this.config.resolveModel(modelId);
+  }
+  // ===========================================================================
+  // Subagent Model Management
+  // ===========================================================================
+  getSubagentModelId(agentType) {
+    const state = this.state;
+    if (agentType) {
+      const perType = state[`subagentModelId_${agentType}`];
+      if (typeof perType === "string") return perType;
+    }
+    const global = state.subagentModelId;
+    return typeof global === "string" ? global : null;
+  }
+  async setSubagentModelId(modelId, agentType) {
+    const key = agentType ? `subagentModelId_${agentType}` : "subagentModelId";
+    void this.setState({ [key]: modelId });
+    await this.persistThreadSetting(key, modelId);
+    this.emit({ type: "subagent_model_changed", modelId, scope: "thread", agentType });
+  }
+  // ===========================================================================
+  // Permissions
+  // ===========================================================================
+  grantSessionCategory(category) {
+    this.sessionGrantedCategories.add(category);
+  }
+  grantSessionTool(toolName) {
+    this.sessionGrantedTools.add(toolName);
+  }
+  getSessionGrants() {
+    return {
+      categories: [...this.sessionGrantedCategories],
+      tools: [...this.sessionGrantedTools]
+    };
+  }
+  getToolCategory(toolName) {
+    return this.config.toolCategoryResolver?.(toolName) ?? null;
+  }
+  setPermissionCategory(category, policy) {
+    const rules = this.getPermissionRules();
+    rules.categories[category] = policy;
+    void this.setState({ permissionRules: rules });
+  }
+  setPermissionTool(toolName, policy) {
+    const rules = this.getPermissionRules();
+    rules.tools[toolName] = policy;
+    void this.setState({ permissionRules: rules });
+  }
+  getPermissionRules() {
+    const state = this.state;
+    const rules = state.permissionRules;
+    return rules ?? { categories: {}, tools: {} };
+  }
+  /**
+   * Resolve whether a tool call should be auto-approved, denied, or asked.
+   * Resolution chain: yolo → per-tool policy → session tool grant →
+   * session category grant → category policy → "ask"
+   */
+  resolveToolApproval(toolName) {
+    const state = this.state;
+    if (state.yolo === true) return "allow";
+    const rules = this.getPermissionRules();
+    const toolPolicy = rules.tools[toolName];
+    if (toolPolicy) return toolPolicy;
+    if (this.sessionGrantedTools.has(toolName)) return "allow";
+    const category = this.getToolCategory(toolName);
+    if (category) {
+      if (this.sessionGrantedCategories.has(category)) return "allow";
+      const categoryPolicy = rules.categories[category];
+      if (categoryPolicy) return categoryPolicy;
+    }
+    return "ask";
+  }
+  // ===========================================================================
+  // Message Handling
+  // ===========================================================================
+  /**
+   * Send a message to the current agent.
+   * Streams the response and emits events.
+   */
+  async sendMessage(content, options) {
+    if (!this.currentThreadId) {
+      const thread = await this.createThread();
+      this.currentThreadId = thread.id;
+    }
+    const operationId = ++this.currentOperationId;
+    this.abortController = new AbortController();
+    const agent = this.getCurrentAgent();
+    this.emit({ type: "agent_start" });
+    try {
+      const requestContext = await this.buildRequestContext();
+      const isYolo = this.state.yolo === true;
+      const streamOptions = {
+        memory: { thread: this.currentThreadId, resource: this.resourceId },
+        abortSignal: this.abortController.signal,
+        requestContext,
+        maxSteps: 1e3,
+        requireToolApproval: !isYolo,
+        modelSettings: { temperature: 1 }
+      };
+      streamOptions.toolsets = await this.buildToolsets(requestContext);
+      let messageInput = content;
+      if (options?.images?.length) {
+        messageInput = {
+          role: "user",
+          content: [
+            { type: "text", text: content },
+            ...options.images.map((img) => ({ type: "file", data: img.data, mediaType: img.mimeType }))
+          ]
+        };
+      }
+      const response = await agent.stream(messageInput, streamOptions);
+      await this.processStream(response);
+      if (this.currentOperationId === operationId) {
+        const reason = this.abortRequested ? "aborted" : "complete";
+        this.emit({ type: "agent_end", reason });
+      }
+    } catch (error) {
+      if (this.currentOperationId !== operationId) return;
+      if (error instanceof Error && error.name === "AbortError") {
+        this.emit({ type: "agent_end", reason: "aborted" });
+      } else if (error instanceof Error && error.message.match(/^Tool .+ not found$/)) {
+        const badTool = error.message.replace("Tool ", "").replace(" not found", "");
+        this.emit({
+          type: "error",
+          error: new Error(`Unknown tool "${badTool}".`),
+          retryable: true
+        });
+        this.followUpQueue.push(
+          `[System] Your previous tool call used "${badTool}" which is not a valid tool. Please retry with the correct tool name.`
+        );
+        this.emit({ type: "agent_end", reason: "error" });
+      } else {
+        const err = error instanceof Error ? error : new Error(String(error));
+        this.emit({ type: "error", error: err });
+        this.emit({ type: "agent_end", reason: "error" });
+      }
+    } finally {
+      if (this.currentOperationId === operationId) {
+        this.abortController = null;
+        this.abortRequested = false;
+      }
+      if (this.currentOperationId === operationId && this.followUpQueue.length > 0) {
+        const next = this.followUpQueue.shift();
+        await this.sendMessage(next);
+      }
+    }
+  }
+  async getMessages(options) {
+    if (!this.currentThreadId) return [];
+    return this.getMessagesForThread(this.currentThreadId, options);
+  }
+  async getMessagesForThread(threadId, options) {
+    if (!this.config.storage) return [];
+    const memoryStorage = await this.getMemoryStorage();
+    const limit = options?.limit;
+    if (limit) {
+      const result2 = await memoryStorage.listMessages({
+        threadId,
+        perPage: limit,
+        page: 0,
+        orderBy: { field: "createdAt", direction: "DESC" }
+      });
+      return result2.messages.map((msg) => this.convertToHarnessMessage(msg)).reverse();
+    }
+    const result = await memoryStorage.listMessages({ threadId, perPage: false });
+    return result.messages.map((msg) => this.convertToHarnessMessage(msg));
+  }
+  async getFirstUserMessageForThread(threadId) {
+    if (!this.config.storage) return null;
+    const memoryStorage = await this.getMemoryStorage();
+    const result = await memoryStorage.listMessages({
+      threadId,
+      perPage: 5,
+      page: 0,
+      orderBy: { field: "createdAt", direction: "ASC" }
+    });
+    const userMsg = result.messages.find((m) => m.role === "user");
+    return userMsg ? this.convertToHarnessMessage(userMsg) : null;
+  }
+  convertToHarnessMessage(msg) {
+    const content = [];
+    for (const part of msg.content.parts) {
+      switch (part.type) {
+        case "text":
+          if (part.text) {
+            content.push({ type: "text", text: part.text });
+          }
+          break;
+        case "reasoning":
+          if (part.reasoning) {
+            content.push({ type: "thinking", thinking: part.reasoning });
+          }
+          break;
+        case "tool-invocation":
+          if (part.toolInvocation) {
+            const inv = part.toolInvocation;
+            content.push({ type: "tool_call", id: inv.toolCallId, name: inv.toolName, args: inv.args });
+            if (inv.state === "result" && inv.result !== void 0) {
+              content.push({
+                type: "tool_result",
+                id: inv.toolCallId,
+                name: inv.toolName,
+                result: inv.result,
+                isError: inv.isError ?? false
+              });
+            }
+          } else if (part.toolCallId && part.toolName) {
+            content.push({ type: "tool_call", id: part.toolCallId, name: part.toolName, args: part.args });
+          }
+          break;
+        case "tool-call":
+          if (part.toolCallId && part.toolName) {
+            content.push({ type: "tool_call", id: part.toolCallId, name: part.toolName, args: part.args });
+          }
+          break;
+        case "tool-result":
+          if (part.toolCallId && part.toolName) {
+            content.push({
+              type: "tool_result",
+              id: part.toolCallId,
+              name: part.toolName,
+              result: part.result,
+              isError: part.isError ?? false
+            });
+          }
+          break;
+      }
+    }
+    return { id: msg.id, role: msg.role, content, createdAt: msg.createdAt };
+  }
+  /**
+   * Process a stream response (shared between sendMessage and tool approval).
+   */
+  async processStream(response) {
+    let currentMessage = {
+      id: this.generateId(),
+      role: "assistant",
+      content: [],
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    const textContentById = /* @__PURE__ */ new Map();
+    const thinkingContentById = /* @__PURE__ */ new Map();
+    for await (const chunk of response.fullStream) {
+      if ("runId" in chunk && chunk.runId) {
+        this.currentRunId = chunk.runId;
+      }
+      switch (chunk.type) {
+        case "text-start": {
+          const textIndex = currentMessage.content.length;
+          currentMessage.content.push({ type: "text", text: "" });
+          textContentById.set(chunk.payload.id, { index: textIndex, text: "" });
+          this.emit({ type: "message_start", message: { ...currentMessage } });
+          break;
+        }
+        case "text-delta": {
+          const textState = textContentById.get(chunk.payload.id);
+          if (textState) {
+            textState.text += chunk.payload.text;
+            const textContent = currentMessage.content[textState.index];
+            if (textContent && textContent.type === "text") {
+              textContent.text = textState.text;
+            }
+            this.emit({ type: "message_update", message: { ...currentMessage } });
+          }
+          break;
+        }
+        case "reasoning-start": {
+          const thinkingIndex = currentMessage.content.length;
+          currentMessage.content.push({ type: "thinking", thinking: "" });
+          thinkingContentById.set(chunk.payload.id, { index: thinkingIndex, text: "" });
+          this.emit({ type: "message_update", message: { ...currentMessage } });
+          break;
+        }
+        case "reasoning-delta": {
+          const thinkingState = thinkingContentById.get(chunk.payload.id);
+          if (thinkingState) {
+            thinkingState.text += chunk.payload.text;
+            const thinkingContent = currentMessage.content[thinkingState.index];
+            if (thinkingContent && thinkingContent.type === "thinking") {
+              thinkingContent.thinking = thinkingState.text;
+            }
+            this.emit({ type: "message_update", message: { ...currentMessage } });
+          }
+          break;
+        }
+        case "tool-call": {
+          const toolCall = chunk.payload;
+          currentMessage.content.push({
+            type: "tool_call",
+            id: toolCall.toolCallId,
+            name: toolCall.toolName,
+            args: toolCall.args
+          });
+          this.emit({
+            type: "tool_start",
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            args: toolCall.args
+          });
+          this.emit({ type: "message_update", message: { ...currentMessage } });
+          break;
+        }
+        case "tool-result": {
+          const toolResult = chunk.payload;
+          currentMessage.content.push({
+            type: "tool_result",
+            id: toolResult.toolCallId,
+            name: toolResult.toolName,
+            result: toolResult.result,
+            isError: toolResult.isError ?? false
+          });
+          this.emit({
+            type: "tool_end",
+            toolCallId: toolResult.toolCallId,
+            result: toolResult.result,
+            isError: toolResult.isError ?? false
+          });
+          this.emit({ type: "message_update", message: { ...currentMessage } });
+          break;
+        }
+        case "tool-error": {
+          const toolError = chunk.payload;
+          this.emit({ type: "tool_end", toolCallId: toolError.toolCallId, result: toolError.error, isError: true });
+          break;
+        }
+        case "tool-call-approval": {
+          const toolCallId = chunk.payload.toolCallId;
+          const toolName = chunk.payload.toolName;
+          const toolArgs = chunk.payload.args;
+          const policy = this.resolveToolApproval(toolName);
+          if (policy === "allow") {
+            const result = await this.handleToolApprove(toolCallId);
+            currentMessage = result.message;
+            return { message: currentMessage };
+          }
+          if (policy === "deny") {
+            const result = await this.handleToolDecline(toolCallId);
+            currentMessage = result.message;
+            return { message: currentMessage };
+          }
+          this.pendingApprovalToolName = toolName;
+          this.emit({ type: "tool_approval_required", toolCallId, toolName, args: toolArgs });
+          const decision = await new Promise((resolve) => {
+            this.pendingApprovalResolve = resolve;
+          });
+          this.pendingApprovalToolName = null;
+          if (decision === "approve") {
+            const result = await this.handleToolApprove(toolCallId);
+            currentMessage = result.message;
+            return { message: currentMessage };
+          } else {
+            const result = await this.handleToolDecline(toolCallId);
+            currentMessage = result.message;
+            return { message: currentMessage };
+          }
+        }
+        case "error": {
+          const streamError = chunk.payload.error instanceof Error ? chunk.payload.error : new Error(String(chunk.payload.error));
+          this.emit({ type: "error", error: streamError });
+          break;
+        }
+        case "step-finish": {
+          const usage = chunk.payload?.output?.usage;
+          if (usage) {
+            const promptTokens = usage.promptTokens ?? 0;
+            const completionTokens = usage.completionTokens ?? 0;
+            const totalTokens = promptTokens + completionTokens;
+            this.tokenUsage.promptTokens += promptTokens;
+            this.tokenUsage.completionTokens += completionTokens;
+            this.tokenUsage.totalTokens += totalTokens;
+            this.persistTokenUsage().catch(() => {
+            });
+            this.emit({ type: "usage_update", usage: { promptTokens, completionTokens, totalTokens } });
+          }
+          break;
+        }
+        case "finish": {
+          const finishReason = chunk.payload.stepResult?.reason;
+          if (finishReason === "stop" || finishReason === "end-turn") {
+            currentMessage.stopReason = "complete";
+          } else if (finishReason === "tool-calls") {
+            currentMessage.stopReason = "tool_use";
+          } else {
+            currentMessage.stopReason = "complete";
+          }
+          break;
+        }
+      }
+    }
+    this.emit({ type: "message_end", message: currentMessage });
+    return { message: currentMessage };
+  }
+  // ===========================================================================
+  // Control
+  // ===========================================================================
+  /**
+   * Abort the current operation.
+   */
+  abort() {
+    if (this.abortController) {
+      this.abortRequested = true;
+      try {
+        this.abortController.abort();
+      } catch {
+      }
+      this.abortController = null;
+    }
+  }
+  /**
+   * Steer the agent mid-stream: aborts current run and sends a new message.
+   */
+  async steer(content) {
+    this.abort();
+    this.followUpQueue = [];
+    await this.sendMessage(content);
+  }
+  /**
+   * Queue a follow-up message to be processed after the current operation completes.
+   */
+  async followUp(content) {
+    if (this.isRunning()) {
+      this.followUpQueue.push(content);
+      this.emit({ type: "follow_up_queued", count: this.followUpQueue.length });
+    } else {
+      await this.sendMessage(content);
+    }
+  }
+  getFollowUpCount() {
+    return this.followUpQueue.length;
+  }
+  isRunning() {
+    return this.abortController !== null;
+  }
+  getCurrentRunId() {
+    return this.currentRunId;
+  }
+  /**
+   * Respond to a pending tool approval from the UI.
+   * "always_allow_category" grants the tool's category for the rest of the session, then approves.
+   */
+  resolveToolApprovalDecision(decision) {
+    if (!this.pendingApprovalResolve) return;
+    if (decision === "always_allow_category") {
+      const tn = this.pendingApprovalToolName;
+      if (tn) {
+        const category = this.getToolCategory(tn);
+        if (category) {
+          this.grantSessionCategory(category);
+        }
+      }
+      this.pendingApprovalResolve("approve");
+    } else {
+      this.pendingApprovalResolve(decision);
+    }
+    this.pendingApprovalResolve = null;
+  }
+  // ===========================================================================
+  // Question & Plan Approval
+  // ===========================================================================
+  /**
+   * Register a pending question resolver.
+   * Called by agent tools (e.g., ask_user) to pause execution until the UI responds.
+   */
+  registerQuestion(questionId, resolve) {
+    this.pendingQuestions.set(questionId, resolve);
+  }
+  /**
+   * Resolve a pending question with the user's answer.
+   * Called by the UI when the user responds to a question dialog.
+   */
+  respondToQuestion(questionId, answer) {
+    const resolve = this.pendingQuestions.get(questionId);
+    if (resolve) {
+      this.pendingQuestions.delete(questionId);
+      resolve(answer);
+    }
+  }
+  /**
+   * Register a pending plan approval resolver.
+   * Called by agent tools (e.g., submit_plan) to pause execution until approval.
+   */
+  registerPlanApproval(planId, resolve) {
+    this.pendingPlanApprovals.set(planId, resolve);
+  }
+  /**
+   * Respond to a pending plan approval.
+   * On approval: switches to the default mode, then resolves the promise.
+   * On rejection: resolves with feedback (stays in current mode).
+   */
+  async respondToPlanApproval(planId, response) {
+    const resolve = this.pendingPlanApprovals.get(planId);
+    if (!resolve) return;
+    if (response.action === "approved") {
+      const defaultMode = this.config.modes.find((m) => m.default) ?? this.config.modes[0];
+      if (defaultMode && defaultMode.id !== this.currentModeId) {
+        await this.switchMode(defaultMode.id);
+      }
+    }
+    this.pendingPlanApprovals.delete(planId);
+    resolve(response);
+  }
+  async handleToolApprove(toolCallId) {
+    if (!this.currentRunId) {
+      throw new Error("No active run to approve tool call for");
+    }
+    const agent = this.getCurrentAgent();
+    if (!this.abortController) {
+      this.abortController = new AbortController();
+    }
+    const requestContext = await this.buildRequestContext();
+    const response = await agent.approveToolCall({
+      runId: this.currentRunId,
+      toolCallId,
+      requireToolApproval: true,
+      memory: this.currentThreadId ? { thread: this.currentThreadId, resource: this.resourceId } : void 0,
+      abortSignal: this.abortController.signal,
+      requestContext,
+      toolsets: await this.buildToolsets(requestContext)
+    });
+    return await this.processStream(response);
+  }
+  async handleToolDecline(toolCallId) {
+    if (!this.currentRunId) {
+      throw new Error("No active run to decline tool call for");
+    }
+    const agent = this.getCurrentAgent();
+    if (!this.abortController) {
+      this.abortController = new AbortController();
+    }
+    const requestContext = await this.buildRequestContext();
+    const response = await agent.declineToolCall({
+      runId: this.currentRunId,
+      toolCallId,
+      requireToolApproval: true,
+      memory: this.currentThreadId ? { thread: this.currentThreadId, resource: this.resourceId } : void 0,
+      abortSignal: this.abortController.signal,
+      requestContext,
+      toolsets: await this.buildToolsets(requestContext)
+    });
+    return await this.processStream(response);
+  }
+  // ===========================================================================
+  // Event System
+  // ===========================================================================
+  /**
+   * Subscribe to harness events. Returns an unsubscribe function.
+   */
+  subscribe(listener) {
+    this.listeners.push(listener);
+    return () => {
+      const index = this.listeners.indexOf(listener);
+      if (index !== -1) {
+        this.listeners.splice(index, 1);
+      }
+    };
+  }
+  emit(event) {
+    for (const listener of this.listeners) {
+      try {
+        const result = listener(event);
+        if (result && typeof result === "object" && "catch" in result) {
+          result.catch((err) => console.error("Error in harness event listener:", err));
+        }
+      } catch (err) {
+        console.error("Error in harness event listener:", err);
+      }
+    }
+  }
+  // ===========================================================================
+  // Runtime Context
+  // ===========================================================================
+  /**
+   * Build the toolsets object that includes built-in harness tools (ask_user, submit_plan,
+   * and optionally subagent) plus any user-configured tools.
+   * Used by sendMessage, handleToolApprove, and handleToolDecline.
+   */
+  async buildToolsets(requestContext) {
+    const builtInTools = {
+      ask_user: askUserTool,
+      submit_plan: submitPlanTool
+    };
+    let resolvedHarnessTools = void 0;
+    if (this.config.tools) {
+      const tools = typeof this.config.tools === "function" ? await this.config.tools({ requestContext }) : this.config.tools;
+      if (tools) {
+        resolvedHarnessTools = tools;
+      }
+    }
+    if (this.config.subagents?.length && this.config.resolveModel) {
+      const currentMode = this.getCurrentMode();
+      builtInTools.subagent = createSubagentTool({
+        subagents: this.config.subagents,
+        resolveModel: this.config.resolveModel,
+        harnessTools: resolvedHarnessTools,
+        fallbackModelId: currentMode?.defaultModelId
+      });
+    }
+    if (resolvedHarnessTools) {
+      return { harnessBuiltIn: builtInTools, harness: resolvedHarnessTools };
+    }
+    return { harnessBuiltIn: builtInTools };
+  }
+  /**
+   * Build request context for agent execution.
+   * Tools can access harness state via requestContext.get('harness').
+   */
+  async buildRequestContext() {
+    const harnessContext = {
+      harnessId: this.id,
+      state: this.getState(),
+      getState: () => this.getState(),
+      setState: (updates) => this.setState(updates),
+      threadId: this.currentThreadId,
+      resourceId: this.resourceId,
+      modeId: this.currentModeId,
+      abortSignal: this.abortController?.signal,
+      workspace: this.workspace,
+      emitEvent: (event) => this.emit(event),
+      registerQuestion: (questionId, resolve) => this.registerQuestion(questionId, resolve),
+      registerPlanApproval: (planId, resolve) => this.registerPlanApproval(planId, resolve),
+      getSubagentModelId: (agentType) => this.getSubagentModelId(agentType)
+    };
+    const requestContext = new RequestContext([["harness", harnessContext]]);
+    if (this.workspaceFn) {
+      harnessContext.workspace = await Promise.resolve(this.workspaceFn({ requestContext }));
+    }
+    return requestContext;
+  }
+  // ===========================================================================
+  // Token Usage
+  // ===========================================================================
+  getTokenUsage() {
+    return { ...this.tokenUsage };
+  }
+  async persistTokenUsage() {
+    if (!this.currentThreadId || !this.config.storage) return;
+    try {
+      const memoryStorage = await this.getMemoryStorage();
+      const thread = await memoryStorage.getThreadById({ threadId: this.currentThreadId });
+      if (thread) {
+        await memoryStorage.saveThread({
+          thread: {
+            ...thread,
+            metadata: { ...thread.metadata, tokenUsage: this.tokenUsage },
+            updatedAt: /* @__PURE__ */ new Date()
+          }
+        });
+      }
+    } catch {
+    }
+  }
+  // ===========================================================================
+  // Workspace
+  // ===========================================================================
+  getWorkspace() {
+    return this.workspace;
+  }
+  hasWorkspace() {
+    return this.config.workspace !== void 0;
+  }
+  isWorkspaceReady() {
+    if (this.workspaceFn) return true;
+    return this.workspaceInitialized && this.workspace !== void 0;
+  }
+  async destroyWorkspace() {
+    if (this.workspaceFn) return;
+    if (this.workspace && this.workspaceInitialized) {
+      try {
+        this.emit({ type: "workspace_status_changed", status: "destroying" });
+        await this.workspace.destroy();
+        this.emit({ type: "workspace_status_changed", status: "destroyed" });
+      } catch (error) {
+        console.warn("Workspace destroy failed:", error);
+      } finally {
+        this.workspaceInitialized = false;
+      }
+    }
+  }
+  // ===========================================================================
+  // Heartbeat Handlers
+  // ===========================================================================
+  startHeartbeats() {
+    const handlers = this.config.heartbeatHandlers;
+    if (!handlers?.length) return;
+    for (const hb of handlers) {
+      if (this.heartbeatTimers.has(hb.id)) continue;
+      const run = async () => {
+        try {
+          await hb.handler();
+        } catch (error) {
+          console.error(`[Heartbeat:${hb.id}] failed:`, error);
+        }
+      };
+      if (hb.immediate !== false) {
+        void run();
+      }
+      const timer = setInterval(run, hb.intervalMs);
+      timer.unref();
+      this.heartbeatTimers.set(hb.id, { timer, shutdown: hb.shutdown });
+    }
+  }
+  registerHeartbeat(handler) {
+    void this.removeHeartbeat(handler.id);
+    const run = async () => {
+      try {
+        await handler.handler();
+      } catch (error) {
+        console.error(`[Heartbeat:${handler.id}] failed:`, error);
+      }
+    };
+    if (handler.immediate !== false) {
+      void run();
+    }
+    const timer = setInterval(run, handler.intervalMs);
+    timer.unref();
+    this.heartbeatTimers.set(handler.id, { timer, shutdown: handler.shutdown });
+  }
+  async removeHeartbeat(id) {
+    const entry = this.heartbeatTimers.get(id);
+    if (entry) {
+      clearInterval(entry.timer);
+      this.heartbeatTimers.delete(id);
+      try {
+        await entry.shutdown?.();
+      } catch (error) {
+        console.error(`[Heartbeat:${id}] shutdown failed:`, error);
+      }
+    }
+  }
+  async stopHeartbeats() {
+    const entries = [...this.heartbeatTimers.entries()];
+    this.heartbeatTimers.clear();
+    for (const [id, entry] of entries) {
+      clearInterval(entry.timer);
+      try {
+        await entry.shutdown?.();
+      } catch (error) {
+        console.error(`[Heartbeat:${id}] shutdown failed:`, error);
+      }
+    }
+  }
+  // ===========================================================================
+  // Session
+  // ===========================================================================
+  async getSession() {
+    return {
+      currentThreadId: this.currentThreadId,
+      currentModeId: this.currentModeId,
+      threads: await this.listThreads()
+    };
+  }
+  // ===========================================================================
+  // Utilities
+  // ===========================================================================
+  generateId() {
+    if (this.config.idGenerator) {
+      return this.config.idGenerator();
+    }
+    return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+};
+
+export { Harness, askUserTool, parseSubagentMeta, submitPlanTool };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map