@revenexx/editor 0.1.0

package/dist/modules/agent/runtime/server/classes/Session/index.js

@@ -0,0 +1,983 @@
+import { z } from "zod";
+import { coerceStringifiedParams } from "../../../shared/toolParams.js";
+import { ToolResult } from "../../../shared/toolResult.js";
+import {
+  buildSystemPrompt,
+  buildSystemPromptEntries
+} from "../../helpers/agentPrompt.js";
+import { provider, models } from "#blokkli-build/agent-server";
+import { send } from "../../helpers/socket.js";
+import {
+  ConversationHistory
+} from "../ConversationHistory/index.js";
+import {
+  UserPromptMessage,
+  AssistantMessage,
+  ToolRelayMessage
+} from "../ConversationMessage/index.js";
+import { resolveSkills } from "../../helpers/skills.js";
+import { classifyError } from "../../helpers/errors.js";
+import { computeStateHash, verifyStateHash } from "../../helpers/security.js";
+import { validateMessages } from "../../helpers/messages.js";
+import { getDefaultModel, createUsageTurn } from "../../helpers/models.js";
+import { buildDefinition, stripSchemaOverhead } from "../../server-tools/index.js";
+import { StreamAccumulator } from "../StreamAccumulator/index.js";
+import loadSkillTool from "../../server-tools/load_skills/index.js";
+import loadToolsTool from "../../server-tools/load_tools/index.js";
+import createPlanTool from "../../server-tools/create_plan/index.js";
+import completePlanStepTool from "../../server-tools/complete_plan_step/index.js";
+const serverTools = [
+  loadSkillTool,
+  loadToolsTool,
+  createPlanTool,
+  completePlanStepTool
+];
+export class Session {
+  /** The single, immutable source of truth for the conversation. */
+  history = new ConversationHistory();
+  pendingToolCalls = /* @__PURE__ */ new Map();
+  abortController = null;
+  isProcessing = false;
+  /** Names of eager tools sent to the LLM on every turn */
+  toolNames = [];
+  /** Names of lazy tools held back until activated via load_tools */
+  lazyToolNames = [];
+  /** Names of lazy tools that have been activated via load_tools */
+  activatedLazyTools = /* @__PURE__ */ new Set();
+  /** Names of skills that have been loaded via load_skills */
+  loadedSkills = /* @__PURE__ */ new Set();
+  /** Page context received from client on init */
+  pageContext;
+  /** Current plan (null when no plan is active) */
+  plan = null;
+  /** Whether any real work (non-server tool calls) happened since the last plan step started */
+  planStepHasWork = false;
+  /** Pending plan approval promise resolver */
+  pendingPlanApproval = null;
+  /** Last generic tool definitions for transcript */
+  lastTools = [];
+  /** Last raw request payload for transcript (dev only) */
+  lastDebugPayload = null;
+  /** Bundled tool metadata map for server-side resolution */
+  bundledToolMap;
+  /** Cache for resolved JSON Schemas (Zod→JSON Schema is deterministic) */
+  jsonSchemaCache = /* @__PURE__ */ new Map();
+  constructor(toolDefinitions) {
+    this.bundledToolMap = new Map(toolDefinitions.map((t) => [t.name, t]));
+  }
+  /**
+   * Resolve a single tool name into a ClientToolDefinition.
+   * Resolves from bundled metadata. Caches the JSON Schema conversion.
+   */
+  resolveToolDefinition(name) {
+    const bundled = this.bundledToolMap.get(name);
+    if (!bundled) return void 0;
+    let inputSchema = this.jsonSchemaCache.get(name);
+    if (!inputSchema) {
+      inputSchema = stripSchemaOverhead(
+        z.toJSONSchema(bundled.paramsSchema)
+      );
+      this.jsonSchemaCache.set(name, inputSchema);
+    }
+    return {
+      name: bundled.name,
+      description: bundled.description,
+      input_schema: inputSchema,
+      ...bundled.lazy ? { lazy: true } : {},
+      category: bundled.category,
+      ...bundled.volatile ? { volatile: true } : {}
+    };
+  }
+  /**
+   * Resolve multiple tool names into ClientToolDefinition objects.
+   * Skips names that cannot be resolved.
+   */
+  resolveToolDefinitions(names) {
+    const result = [];
+    for (const name of names) {
+      const def = this.resolveToolDefinition(name);
+      if (def) {
+        result.push(def);
+      }
+    }
+    return result;
+  }
+  /**
+   * Look up name + description for a tool.
+   */
+  getToolSummary(name) {
+    const bundled = this.bundledToolMap.get(name);
+    if (!bundled) return void 0;
+    return { name: bundled.name, description: bundled.description };
+  }
+  // --------------------------------------------------------------------------
+  // Public methods
+  // --------------------------------------------------------------------------
+  init(toolNames, pageContext) {
+    this.toolNames = [];
+    this.lazyToolNames = [];
+    for (const name of toolNames) {
+      const bundled = this.bundledToolMap.get(name);
+      const isLazy = bundled?.lazy ?? false;
+      if (isLazy) {
+        this.lazyToolNames.push(name);
+      } else {
+        this.toolNames.push(name);
+      }
+    }
+    this.activatedLazyTools = /* @__PURE__ */ new Set();
+    this.loadedSkills = /* @__PURE__ */ new Set();
+    this.pageContext = pageContext;
+  }
+  start(peer, prompt, apiKey, authSecret, selectedBlocks, autoLoadTools, autoLoadSkills, preSeededResults, autoExecuteTools, rollbackToUserMessageIndex) {
+    if (this.isProcessing) {
+      send(peer, {
+        type: "error",
+        errorType: "bad_request",
+        message: "Agent is already processing a request"
+      });
+      return;
+    }
+    if (rollbackToUserMessageIndex !== void 0) {
+      try {
+        this.truncateAtUserMessage(rollbackToUserMessageIndex);
+      } catch (e) {
+        send(peer, {
+          type: "error",
+          errorType: "bad_request",
+          message: e instanceof Error ? e.message : "Rollback target out of range"
+        });
+        return;
+      }
+    }
+    this.isProcessing = true;
+    this.runAgentLoop(
+      peer,
+      prompt,
+      apiKey,
+      authSecret,
+      selectedBlocks,
+      autoLoadTools,
+      autoLoadSkills,
+      preSeededResults,
+      autoExecuteTools
+    );
+  }
+  /**
+   * Remove the Nth real user turn (0-based) and every message after it.
+   * "Real user turn" excludes tool-result relays. Throws if the index is
+   * out of range — typically because the target turn has been pruned away.
+   */
+  truncateAtUserMessage(targetIndex) {
+    this.history.truncateAtUserTurn(targetIndex);
+    this.lastTools = [];
+    this.lastDebugPayload = null;
+    for (const pending of this.pendingToolCalls.values()) {
+      pending.reject(new Error("Rollback cancelled pending tool call"));
+    }
+    this.pendingToolCalls.clear();
+    if (this.pendingPlanApproval) {
+      this.pendingPlanApproval.resolve(false);
+      this.pendingPlanApproval = null;
+    }
+  }
+  resolveToolResult(callId, result) {
+    const pending = this.pendingToolCalls.get(callId);
+    if (pending) {
+      pending.resolve(result);
+    }
+  }
+  cancel(peer) {
+    this.abortController?.abort();
+    for (const pending of this.pendingToolCalls.values()) {
+      pending.reject(new Error("Cancelled"));
+    }
+    this.pendingToolCalls.clear();
+    if (this.pendingPlanApproval) {
+      this.pendingPlanApproval.resolve(false);
+      this.pendingPlanApproval = null;
+    }
+    send(peer, { type: "done" });
+  }
+  acceptChanges(peer, authSecret) {
+    this.safePushUserMessage(`[System: Changes accepted and applied.]`);
+    send(peer, { type: "done", message: "Changes accepted" });
+    this.sendConversationState(peer, authSecret);
+  }
+  rejectChanges(peer, authSecret) {
+    this.safePushUserMessage(
+      `[System: Changes rejected. All pending changes have been reverted. The page is back to its previous state.]`
+    );
+    send(peer, { type: "done", message: "Changes rejected" });
+    this.sendConversationState(peer, authSecret);
+  }
+  approvePlan() {
+    if (this.pendingPlanApproval) {
+      this.pendingPlanApproval.resolve(true);
+      this.pendingPlanApproval = null;
+    }
+  }
+  rejectPlan() {
+    if (this.pendingPlanApproval) {
+      this.pendingPlanApproval.resolve(false);
+      this.pendingPlanApproval = null;
+    }
+  }
+  getTranscript(peer) {
+    send(peer, {
+      type: "transcript",
+      transcript: this.buildTranscript()
+    });
+  }
+  newConversation(peer, authSecret) {
+    this.abortController?.abort();
+    for (const pending of this.pendingToolCalls.values()) {
+      pending.reject(new Error("Cancelled"));
+    }
+    this.pendingToolCalls.clear();
+    this.history.clear();
+    this.lastTools = [];
+    this.lastDebugPayload = null;
+    this.activatedLazyTools.clear();
+    this.loadedSkills.clear();
+    this.plan = null;
+    if (this.pendingPlanApproval) {
+      this.pendingPlanApproval.resolve(false);
+      this.pendingPlanApproval = null;
+    }
+    send(peer, { type: "done" });
+    this.sendConversationState(peer, authSecret);
+  }
+  cleanup() {
+    this.abortController?.abort();
+    for (const pending of this.pendingToolCalls.values()) {
+      pending.reject(new Error("Session closed"));
+    }
+    this.pendingToolCalls.clear();
+    if (this.pendingPlanApproval) {
+      this.pendingPlanApproval.resolve(false);
+      this.pendingPlanApproval = null;
+    }
+    this.plan = null;
+    this.history.clear();
+    this.toolNames = [];
+    this.lazyToolNames = [];
+    this.activatedLazyTools.clear();
+    this.loadedSkills.clear();
+    this.pageContext = void 0;
+  }
+  /**
+   * Build a persistence snapshot and send it to the client.
+   */
+  sendConversationState(peer, authSecret) {
+    const state = this.getConversationStateForPersistence(authSecret);
+    send(peer, { type: "conversation_state", state });
+  }
+  /**
+   * Create an aggressively pruned snapshot of the current conversation
+   * for client-side persistence.
+   */
+  getConversationStateForPersistence(authSecret) {
+    const prunedMessages = this.history.projectForPersistence();
+    const activatedLazyTools = Array.from(this.activatedLazyTools);
+    const hash = computeStateHash(
+      prunedMessages,
+      activatedLazyTools,
+      authSecret
+    );
+    return {
+      messages: prunedMessages,
+      activatedLazyTools,
+      hash
+    };
+  }
+  /**
+   * Restore conversation state from a client-provided snapshot.
+   * Verifies HMAC integrity before loading.
+   */
+  restoreConversation(state, authSecret) {
+    if (!verifyStateHash(state, authSecret)) {
+      return { success: false, reason: "Invalid state hash" };
+    }
+    const issues = validateMessages(state.messages);
+    if (issues.length > 0) {
+      return { success: false, reason: "Invalid message structure" };
+    }
+    this.history.replaceAll(state.messages);
+    this.lastTools = [];
+    const validLazyToolNames = new Set(this.lazyToolNames);
+    this.activatedLazyTools = new Set(
+      state.activatedLazyTools.filter((name) => validLazyToolNames.has(name))
+    );
+    this.plan = null;
+    return { success: true };
+  }
+  // --------------------------------------------------------------------------
+  // Private methods
+  // --------------------------------------------------------------------------
+  /**
+   * Convert the server plan to a client-facing plan (strips descriptions).
+   */
+  toClientPlan() {
+    if (!this.plan) return null;
+    return {
+      title: this.plan.title,
+      steps: this.plan.steps.map(
+        (s) => ({
+          label: s.label,
+          status: s.status
+        })
+      )
+    };
+  }
+  /**
+   * Build an ActivePlanContext from the current plan state,
+   * or undefined if no plan step is in progress.
+   */
+  getActivePlanContext() {
+    const currentStep = this.plan?.steps.find((s) => s.status === "in_progress");
+    if (!this.plan || !currentStep) return void 0;
+    return {
+      title: this.plan.title,
+      totalSteps: this.plan.steps.length,
+      completedSteps: this.plan.steps.filter((s) => s.status === "completed").length,
+      currentStep: {
+        label: currentStep.label,
+        description: currentStep.description
+      },
+      remainingSteps: this.plan.steps.filter((s) => s.status === "pending").map((s) => s.label)
+    };
+  }
+  /**
+   * Wait for the user to approve or reject the plan.
+   */
+  waitForPlanApproval() {
+    return new Promise((resolve) => {
+      this.pendingPlanApproval = { resolve };
+    });
+  }
+  async runAgentLoop(peer, prompt, apiKey, authSecret, selectedBlocks, autoLoadTools, autoLoadSkills, preSeededResults, autoExecuteTools) {
+    if (this.toolNames.length === 0) {
+      this.isProcessing = false;
+      send(peer, {
+        type: "error",
+        errorType: "bad_request",
+        message: "No tools available. Client must send init message with tools first."
+      });
+      return;
+    }
+    if (!this.pageContext) {
+      this.isProcessing = false;
+      send(peer, {
+        type: "error",
+        errorType: "bad_request",
+        message: "No page context available. Client must send init message with pageContext first."
+      });
+      return;
+    }
+    const resolvedSkills = resolveSkills(this.pageContext);
+    if (autoLoadTools?.length) {
+      for (const name of autoLoadTools) {
+        if (this.lazyToolNames.includes(name) && !this.activatedLazyTools.has(name)) {
+          this.activatedLazyTools.add(name);
+        }
+      }
+    }
+    const autoLoadedSkillBlocks = [];
+    if (autoLoadSkills?.length) {
+      for (const skillName of autoLoadSkills) {
+        const skill = resolvedSkills.find((s) => s.name === skillName);
+        if (!skill || this.loadedSkills.has(skill.name)) continue;
+        this.loadedSkills.add(skill.name);
+        for (const toolName of skill.tools) {
+          if (this.lazyToolNames.includes(toolName) && !this.activatedLazyTools.has(toolName)) {
+            this.activatedLazyTools.add(toolName);
+          }
+        }
+        autoLoadedSkillBlocks.push({
+          type: "skill",
+          name: skill.name,
+          text: `# Skill: ${skill.name}
+
+${skill.content}`
+        });
+      }
+    }
+    const userParts = [];
+    if (selectedBlocks?.length) {
+      const formatted = selectedBlocks.map((b) => `${b.bundle} (${b.uuid})`).join(", ");
+      userParts.push(
+        selectedBlocks.length === 1 ? `[User has selected one block: ${formatted}]` : `[User has selected: ${formatted}]`
+      );
+    }
+    userParts.push(prompt);
+    const userMessage = autoLoadedSkillBlocks.length > 0 ? new UserPromptMessage([
+      ...autoLoadedSkillBlocks,
+      { type: "text", text: userParts.join("\n\n") }
+    ]) : new UserPromptMessage(userParts.join("\n\n"));
+    this.history.append(userMessage);
+    if (preSeededResults?.length) {
+      for (let i = 0; i < preSeededResults.length; i++) {
+        const preSeeded = preSeededResults[i];
+        const toolUseId = `preseed_${i}`;
+        this.pushToolExchange(
+          toolUseId,
+          preSeeded.toolName,
+          preSeeded.params,
+          ToolResult.fromWire(JSON.stringify(preSeeded.result))
+        );
+      }
+    }
+    let allAutoToolsSkipLlm = false;
+    if (autoExecuteTools?.length) {
+      let hasErrors = false;
+      let allSkip = true;
+      for (let i = 0; i < autoExecuteTools.length; i++) {
+        const autoTool = autoExecuteTools[i];
+        const callId = `auto_${i}`;
+        const toolUseId = `auto_tu_${i}`;
+        send(peer, {
+          type: "tool_call",
+          callId,
+          tool: autoTool.toolName,
+          params: autoTool.params
+        });
+        try {
+          const clientResult = await this.waitForToolResult(callId);
+          let result;
+          if (clientResult.error) {
+            hasErrors = true;
+            allSkip = false;
+            result = ToolResult.error(clientResult.error);
+          } else {
+            if (!clientResult.skipLlmResponse) {
+              allSkip = false;
+            }
+            result = ToolResult.fromClientResult(clientResult.result);
+          }
+          this.pushToolExchange(
+            toolUseId,
+            autoTool.toolName,
+            autoTool.params,
+            result
+          );
+        } catch {
+          hasErrors = true;
+          allSkip = false;
+          this.pushToolExchange(
+            toolUseId,
+            autoTool.toolName,
+            autoTool.params,
+            ToolResult.error("Auto-executed tool call was cancelled.")
+          );
+        }
+      }
+      allAutoToolsSkipLlm = allSkip && !hasErrors;
+    }
+    if (allAutoToolsSkipLlm) {
+      send(peer, { type: "done" });
+      this.sendConversationState(peer, authSecret);
+      this.isProcessing = false;
+      return;
+    }
+    this.abortController = new AbortController();
+    let toolCallCounter = 0;
+    let planRetryCount = 0;
+    let streamRetryCount = 0;
+    const MAX_STREAM_RETRIES = 1;
+    let lastToolCallKey = "";
+    let consecutiveIdenticalCalls = 0;
+    const MAX_IDENTICAL_CALLS = 2;
+    let consecutiveValidationFailures = 0;
+    const MAX_HIDDEN_VALIDATION_FAILURES = 2;
+    try {
+      while (true) {
+        if (this.abortController.signal.aborted) {
+          break;
+        }
+        send(peer, { type: "thinking" });
+        const accumulator = new StreamAccumulator();
+        const assistantContent = accumulator.blocks;
+        const toolResults = [];
+        const extraBlocks = [];
+        let messagesCommittedByPlanTool = false;
+        const eagerTools = this.resolveToolDefinitions(this.toolNames);
+        const activatedToolNames = this.lazyToolNames.filter(
+          (name) => this.activatedLazyTools.has(name)
+        );
+        const activatedTools = this.resolveToolDefinitions(activatedToolNames);
+        const unloadedLazyToolNames = this.lazyToolNames.filter(
+          (name) => !this.activatedLazyTools.has(name)
+        );
+        const unloadedLazyTools = unloadedLazyToolNames.map((name) => this.getToolSummary(name)).filter(
+          (s) => s !== void 0
+        );
+        const defCtx = {
+          resolvedSkills,
+          plan: this.plan,
+          unloadedLazyTools,
+          lazyToolNames: this.lazyToolNames
+        };
+        const serverToolDefs = serverTools.map((t) => buildDefinition(t, defCtx)).filter((d) => d !== null);
+        const allTools = [...serverToolDefs, ...eagerTools, ...activatedTools];
+        this.lastTools = allTools;
+        const lazyToolSummaries = this.lazyToolNames.filter((name) => !this.activatedLazyTools.has(name)).map((name) => this.getToolSummary(name)).filter(
+          (s) => s !== void 0
+        );
+        const systemPrompt = buildSystemPrompt(
+          this.pageContext,
+          resolvedSkills,
+          lazyToolSummaries,
+          this.getActivePlanContext(),
+          this.loadedSkills
+        );
+        const stream = provider.createStream(
+          {
+            apiKey,
+            model: getDefaultModel(models)?.name ?? ""
+          },
+          {
+            systemPrompt,
+            // Pure projection of the immutable history — recomputed each round
+            // from pristine canonical (applies the age + token-budget ceilings
+            // and eager volatile-staleness without ever mutating the source).
+            messages: this.history.projectForLlm(this.volatileLookup()),
+            tools: allTools,
+            maxTokens: 4096,
+            signal: this.abortController.signal
+          }
+        );
+        try {
+          for await (const event of stream) {
+            if (this.abortController?.signal.aborted) {
+              break;
+            }
+            switch (event.type) {
+              case "debug_request":
+                this.lastDebugPayload = event.payload;
+                break;
+              case "text_start":
+                accumulator.startText();
+                break;
+              case "text_delta": {
+                const transformed = accumulator.pushTextDelta(event.text);
+                if (transformed !== null) {
+                  send(peer, { type: "text_delta", content: transformed });
+                }
+                break;
+              }
+              case "text_end":
+                accumulator.endText();
+                break;
+              case "tool_use_start":
+                accumulator.startToolUse(event.id, event.name);
+                break;
+              case "tool_use_delta":
+                accumulator.pushToolUseDelta(event.partial_json);
+                break;
+              case "tool_use_end": {
+                const finished = accumulator.finishToolUse();
+                if (finished) {
+                  if (!finished.ok) {
+                    toolResults.push({
+                      type: "tool_result",
+                      tool_use_id: finished.id,
+                      content: JSON.stringify({
+                        error: "Your tool call produced malformed JSON input. Please try again."
+                      }),
+                      is_error: true
+                    });
+                    break;
+                  }
+                  const { id: toolUseId, name: toolName, input } = finished;
+                  const inputJson = finished.inputJson;
+                  const callId = `tc_${toolCallCounter++}`;
+                  const toolCallKey = toolName + ":" + inputJson;
+                  if (toolCallKey === lastToolCallKey) {
+                    consecutiveIdenticalCalls++;
+                  } else {
+                    lastToolCallKey = toolCallKey;
+                    consecutiveIdenticalCalls = 1;
+                  }
+                  if (consecutiveIdenticalCalls > MAX_IDENTICAL_CALLS) {
+                    toolResults.push({
+                      type: "tool_result",
+                      tool_use_id: toolUseId,
+                      content: JSON.stringify({
+                        error: `You have called "${toolName}" ${consecutiveIdenticalCalls} times in a row with identical parameters and received the same result each time. Stop repeating this call. Use the information you already have or try a different approach.`
+                      }),
+                      is_error: true
+                    });
+                    break;
+                  }
+                  const matchedServerTool = serverTools.find(
+                    (t) => t.name === toolName
+                  );
+                  if (matchedServerTool) {
+                    const dispatch = await this.dispatchServerTool(
+                      matchedServerTool,
+                      {
+                        toolUseId,
+                        input,
+                        defCtx,
+                        resolvedSkills,
+                        peer,
+                        assistantContent
+                      }
+                    );
+                    toolResults.push(...dispatch.toolResults);
+                    if (dispatch.extraBlocks) {
+                      extraBlocks.push(...dispatch.extraBlocks);
+                    }
+                    if (dispatch.messagesCommitted) {
+                      messagesCommittedByPlanTool = true;
+                    }
+                    break;
+                  }
+                  const validation = this.validateClientToolInput(
+                    toolName,
+                    input
+                  );
+                  if (!validation.ok && consecutiveValidationFailures < MAX_HIDDEN_VALIDATION_FAILURES) {
+                    consecutiveValidationFailures++;
+                    toolResults.push({
+                      type: "tool_result",
+                      tool_use_id: toolUseId,
+                      content: JSON.stringify({ error: validation.error }),
+                      is_error: true
+                    });
+                    break;
+                  }
+                  consecutiveValidationFailures = 0;
+                  toolResults.push(
+                    ...await this.dispatchClientTool({
+                      toolUseId,
+                      toolName,
+                      callId,
+                      input,
+                      peer
+                    })
+                  );
+                }
+                break;
+              }
+              case "reasoning_summary":
+                assistantContent.push({
+                  type: "reasoning",
+                  id: event.id,
+                  text: event.text,
+                  encryptedContent: event.encryptedContent
+                });
+                break;
+              case "message_end": {
+                const usage = createUsageTurn(event, getDefaultModel(models));
+                if (usage) {
+                  send(peer, { type: "usage", usage });
+                }
+                break;
+              }
+              case "error":
+                throw event.error;
+            }
+          }
+        } catch (streamError) {
+          const isApiError = typeof streamError.status === "number";
+          const isRetryable = !isApiError && toolResults.length === 0;
+          if (isRetryable && streamRetryCount < MAX_STREAM_RETRIES) {
+            streamRetryCount++;
+            console.warn(
+              `[blokkli agent] Transient stream error, retrying (attempt ${streamRetryCount}/${MAX_STREAM_RETRIES}):`,
+              streamError
+            );
+            continue;
+          }
+          if (isRetryable && this.history.peekLast() === userMessage) {
+            this.history.popLast();
+            console.error(
+              "[blokkli agent] Transient stream error, retries exhausted:",
+              streamError
+            );
+            const classified = classifyError(streamError);
+            send(peer, { type: "error", ...classified, retryable: true });
+            break;
+          }
+          throw streamError;
+        }
+        if (this.abortController?.signal.aborted) {
+          break;
+        }
+        if (messagesCommittedByPlanTool) {
+          this.planStepHasWork = false;
+          continue;
+        }
+        let assistantNames;
+        if (assistantContent.length) {
+          const assistant = new AssistantMessage([...assistantContent]);
+          assistantNames = assistant.toolUseNames();
+          this.history.append(assistant);
+        }
+        if (toolResults.length) {
+          const relay = ToolRelayMessage.fromWire({
+            role: "user",
+            content: [...toolResults, ...extraBlocks]
+          }).withResolvedNames((id) => assistantNames?.get(id));
+          this.history.append(relay);
+          planRetryCount = 0;
+          streamRetryCount = 0;
+        }
+        if (toolResults.length === 0) {
+          const hasActivePlan = this.plan && this.plan.steps.some((s) => s.status === "in_progress");
+          if (hasActivePlan && planRetryCount < 2) {
+            planRetryCount++;
+            this.safePushUserMessage("[Continue with the plan.]");
+            continue;
+          }
+          const finalMessage = assistantContent.filter(
+            (c) => c.type === "text"
+          ).map((t) => t.text).join("\n").trim();
+          send(peer, { type: "done", message: finalMessage || void 0 });
+          break;
+        }
+      }
+    } catch (error) {
+      if (error.name !== "AbortError" && !this.abortController?.signal.aborted) {
+        console.error("Agent loop error:", error);
+        const classified = classifyError(error);
+        send(peer, { type: "error", ...classified });
+      }
+    } finally {
+      this.isProcessing = false;
+      this.abortController = null;
+      this.sendConversationState(peer, authSecret);
+    }
+  }
+  waitForToolResult(callId) {
+    return new Promise((resolve, reject) => {
+      this.pendingToolCalls.set(callId, {
+        resolve: (result) => {
+          this.pendingToolCalls.delete(callId);
+          resolve(result);
+        },
+        reject: (error) => {
+          this.pendingToolCalls.delete(callId);
+          reject(error);
+        }
+      });
+    });
+  }
+  /**
+   * Build the context object passed to a server-side tool handler. `assistantContent`
+   * is the live block array for the current turn — `commitMessagesEarly` flushes and
+   * resets it in place, so it must be the same reference the stream loop appends to.
+   */
+  buildServerToolContext(args) {
+    const { toolUseId, peer, resolvedSkills, assistantContent } = args;
+    return {
+      toolUseId,
+      send: (msg) => send(peer, msg),
+      resolvedSkills,
+      lazyToolNames: this.lazyToolNames,
+      activatedLazyTools: this.activatedLazyTools,
+      loadedSkills: this.loadedSkills,
+      plan: this.plan,
+      setPlan: (p) => {
+        this.plan = p;
+      },
+      toClientPlan: () => this.toClientPlan(),
+      waitForPlanApproval: () => this.waitForPlanApproval(),
+      assistantContent,
+      commitMessagesEarly: (toolResult) => {
+        let names;
+        if (assistantContent.length) {
+          const assistant = new AssistantMessage([...assistantContent]);
+          names = assistant.toolUseNames();
+          this.history.append(assistant);
+          assistantContent.length = 0;
+        }
+        this.history.append(
+          ToolRelayMessage.fromWire({
+            role: "user",
+            content: [toolResult]
+          }).withResolvedNames((id) => names?.get(id))
+        );
+      },
+      updateLastToolResult: (id, content) => {
+        this.history.replaceLastResult(id, ToolResult.fromWire(content));
+      },
+      planStepHasWork: this.planStepHasWork,
+      markPlanStepWork: () => {
+        this.planStepHasWork = true;
+      },
+      resetPlanStepWork: () => {
+        this.planStepHasWork = false;
+      }
+    };
+  }
+  /**
+   * Dispatch a server-side tool: reject if unavailable, coerce + validate input,
+   * run the handler. Returns the blocks to merge into the turn's results.
+   */
+  async dispatchServerTool(tool, args) {
+    const { toolUseId, input, defCtx, resolvedSkills, peer, assistantContent } = args;
+    if (tool.isAvailable && !tool.isAvailable(defCtx)) {
+      return {
+        toolResults: [
+          {
+            type: "tool_result",
+            tool_use_id: toolUseId,
+            content: JSON.stringify({
+              error: "This tool is not available right now."
+            }),
+            is_error: true
+          }
+        ]
+      };
+    }
+    const handlerCtx = this.buildServerToolContext({
+      toolUseId,
+      peer,
+      resolvedSkills,
+      assistantContent
+    });
+    try {
+      const parsed = tool.inputSchema(defCtx).parse(coerceStringifiedParams(input));
+      const result = await tool.handle(handlerCtx, parsed);
+      return {
+        toolResults: result.toolResults,
+        extraBlocks: result.extraBlocks,
+        messagesCommitted: result.messagesCommitted
+      };
+    } catch (e) {
+      return {
+        toolResults: [
+          {
+            type: "tool_result",
+            tool_use_id: toolUseId,
+            content: JSON.stringify({
+              error: `Invalid input: ${e.message}`
+            }),
+            is_error: true
+          }
+        ]
+      };
+    }
+  }
+  /**
+   * Dispatch a client-side tool: send the call to the peer and await its result.
+   * An `agentMessage` on the result replaces the `label` in the payload fed back
+   * to the LLM (the label is UI-only). Returns the tool_result block(s).
+   */
+  /**
+   * Validate an LLM-generated client tool call against its Zod `paramsSchema`
+   * (the same schema the client parses with), server-side, before dispatching
+   * to the peer. Returns an error string on a schema failure so the caller can
+   * reject it silently. Unknown tools pass through (handled by normal dispatch).
+   */
+  validateClientToolInput(toolName, input) {
+    const bundled = this.bundledToolMap.get(toolName);
+    if (!bundled) return { ok: true };
+    const parsed = bundled.paramsSchema.safeParse(
+      coerceStringifiedParams(input)
+    );
+    if (parsed.success) return { ok: true };
+    return {
+      ok: false,
+      error: `Invalid input: ${z.prettifyError(parsed.error)}`
+    };
+  }
+  async dispatchClientTool(args) {
+    const { toolUseId, toolName, callId, input, peer } = args;
+    send(peer, {
+      type: "tool_call",
+      callId,
+      tool: toolName,
+      params: input
+    });
+    try {
+      const clientResult = await this.waitForToolResult(callId);
+      if (clientResult.error) {
+        return [
+          {
+            type: "tool_result",
+            tool_use_id: toolUseId,
+            content: JSON.stringify({ error: clientResult.error }),
+            is_error: true
+          }
+        ];
+      }
+      let resultForLLM = clientResult.result;
+      if (typeof resultForLLM === "object" && resultForLLM !== null && "agentMessage" in resultForLLM) {
+        const { agentMessage, ...rest } = resultForLLM;
+        resultForLLM = { ...rest, label: agentMessage };
+      }
+      this.planStepHasWork = true;
+      return [
+        {
+          type: "tool_result",
+          tool_use_id: toolUseId,
+          content: JSON.stringify(resultForLLM)
+        }
+      ];
+    } catch (error) {
+      return [
+        {
+          type: "tool_result",
+          tool_use_id: toolUseId,
+          content: JSON.stringify({ error: error.message }),
+          is_error: true
+        }
+      ];
+    }
+  }
+  /**
+   * Append a synthetic assistant `tool_use` + user `tool_result` message pair —
+   * the shape used to inject pre-seeded results and to record auto-executed tool
+   * calls before the LLM loop starts.
+   */
+  pushToolExchange(toolUseId, toolName, input, result) {
+    this.history.appendToolExchange(
+      new AssistantMessage([
+        { type: "tool_use", id: toolUseId, name: toolName, input }
+      ]),
+      new ToolRelayMessage([{ toolUseId, toolName, result }])
+    );
+  }
+  /**
+   * Safely push a user message, merging with the last message if it's also a
+   * user message — the LLM API rejects consecutive same-role messages.
+   */
+  safePushUserMessage(text) {
+    this.history.mergeOrAppendUserText(text);
+  }
+  /**
+   * Whether a tool's results go stale after a mutation — used by the live
+   * projection's eager volatile eviction. Volatility is a property of the tool
+   * definition, so it holds regardless of the current tool set.
+   */
+  volatileLookup() {
+    return (name) => !!(name && this.bundledToolMap.get(name)?.volatile);
+  }
+  buildTranscript() {
+    const system = this.pageContext ? buildSystemPromptEntries(
+      this.pageContext,
+      resolveSkills(this.pageContext),
+      this.lazyToolNames.map((name) => this.getToolSummary(name)).filter(
+        (s) => s !== void 0
+      ),
+      this.getActivePlanContext(),
+      this.loadedSkills
+    ) : [];
+    const messages = this.history.buildTranscriptMessages(this.volatileLookup());
+    const tools = this.lastTools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.input_schema
+    }));
+    return {
+      system,
+      messages,
+      tools,
+      ...this.lastDebugPayload ? { lastRequest: this.lastDebugPayload } : {}
+    };
+  }
+}