@blokkli/editor 2.0.0-alpha.58 → 2.0.0-alpha.59

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

@@ -1,23 +1,31 @@
 import { z } from "zod";
-import { buildSystemPrompt, buildSystemPromptEntries } from "./agentPrompt.js";
+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 {
-  send,
-  KEEP_RECENT_TURNS,
-  resolveSkills,
-  transformText,
-  classifyError,
-  pruneMessages,
-  pruneForPersistence,
-  computeStateHash,
-  verifyStateHash,
-  validateMessages
-} from "./helpers.js";
-import { buildDefinition, stripSchemaOverhead } from "./server-tools/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";
+  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,
@@ -25,7 +33,8 @@ const serverTools = [
   completePlanStepTool
 ];
 export class Session {
-  messages = [];
+  /** The single, immutable source of truth for the conversation. */
+  history = new ConversationHistory();
   pendingToolCalls = /* @__PURE__ */ new Map();
   abortController = null;
   isProcessing = false;
@@ -45,8 +54,6 @@ export class Session {
   planStepHasWork = false;
   /** Pending plan approval promise resolver */
   pendingPlanApproval = null;
-  /** Pre-pruned messages snapshot for transcript (captured before pruneMessages) */
-  unprunedMessages = [];
   /** Last generic tool definitions for transcript */
   lastTools = [];
   /** Last raw request payload for transcript (dev only) */
@@ -122,7 +129,7 @@ export class Session {
     this.loadedSkills = /* @__PURE__ */ new Set();
     this.pageContext = pageContext;
   }
-  start(peer, prompt, apiKey, authSecret, selectedUuids, autoLoadTools, autoLoadSkills, preSeededResults, autoExecuteTools) {
+  start(peer, prompt, apiKey, authSecret, selectedUuids, autoLoadTools, autoLoadSkills, preSeededResults, autoExecuteTools, rollbackToUserMessageIndex) {
     if (this.isProcessing) {
       send(peer, {
         type: "error",
@@ -131,6 +138,19 @@ export class Session {
       });
       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,
@@ -143,6 +163,24 @@ export class Session {
       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) {
@@ -193,8 +231,7 @@ export class Session {
   }
   newConversation(peer, authSecret) {
     this.abortController?.abort();
-    this.messages = [];
-    this.unprunedMessages = [];
+    this.history.clear();
     this.lastTools = [];
     this.lastDebugPayload = null;
     this.activatedLazyTools.clear();
@@ -218,7 +255,7 @@ export class Session {
       this.pendingPlanApproval = null;
     }
     this.plan = null;
-    this.messages = [];
+    this.history.clear();
     this.toolNames = [];
     this.lazyToolNames = [];
     this.activatedLazyTools.clear();
@@ -237,7 +274,7 @@ export class Session {
    * for client-side persistence.
    */
   getConversationStateForPersistence(authSecret) {
-    const prunedMessages = pruneForPersistence(this.messages);
+    const prunedMessages = this.history.projectForPersistence();
     const activatedLazyTools = Array.from(this.activatedLazyTools);
     const hash = computeStateHash(
       prunedMessages,
@@ -262,8 +299,7 @@ export class Session {
     if (issues.length > 0) {
       return { success: false, reason: "Invalid message structure" };
     }
-    this.messages = state.messages;
-    this.unprunedMessages = [];
+    this.history.replaceAll(state.messages);
     this.lastTools = [];
     const validLazyToolNames = new Set(this.lazyToolNames);
     this.activatedLazyTools = new Set(
@@ -318,6 +354,7 @@ export class Session {
   }
   async runAgentLoop(peer, prompt, apiKey, authSecret, selectedUuids, autoLoadTools, autoLoadSkills, preSeededResults, autoExecuteTools) {
     if (this.toolNames.length === 0) {
+      this.isProcessing = false;
       send(peer, {
         type: "error",
         errorType: "bad_request",
@@ -326,6 +363,7 @@ export class Session {
       return;
     }
     if (!this.pageContext) {
+      this.isProcessing = false;
       send(peer, {
         type: "error",
         errorType: "bad_request",
@@ -368,39 +406,21 @@ ${skill.content}`
       );
     }
     userParts.push(prompt);
-    const userMessage = autoLoadedSkillBlocks.length > 0 ? {
-      role: "user",
-      content: [
-        ...autoLoadedSkillBlocks,
-        { type: "text", text: userParts.join("\n\n") }
-      ]
-    } : { role: "user", content: userParts.join("\n\n") };
-    this.messages.push(userMessage);
+    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.messages.push({
-          role: "assistant",
-          content: [
-            {
-              type: "tool_use",
-              id: toolUseId,
-              name: preSeeded.toolName,
-              input: preSeeded.params
-            }
-          ]
-        });
-        this.messages.push({
-          role: "user",
-          content: [
-            {
-              type: "tool_result",
-              tool_use_id: toolUseId,
-              content: JSON.stringify(preSeeded.result)
-            }
-          ]
-        });
+        this.pushToolExchange(
+          toolUseId,
+          preSeeded.toolName,
+          preSeeded.params,
+          ToolResult.fromWire(JSON.stringify(preSeeded.result))
+        );
       }
     }
     let allAutoToolsSkipLlm = false;
@@ -419,78 +439,32 @@ ${skill.content}`
         });
         try {
           const clientResult = await this.waitForToolResult(callId);
-          this.messages.push({
-            role: "assistant",
-            content: [
-              {
-                type: "tool_use",
-                id: toolUseId,
-                name: autoTool.toolName,
-                input: autoTool.params
-              }
-            ]
-          });
+          let result;
           if (clientResult.error) {
             hasErrors = true;
             allSkip = false;
-            this.messages.push({
-              role: "user",
-              content: [
-                {
-                  type: "tool_result",
-                  tool_use_id: toolUseId,
-                  content: JSON.stringify({ error: clientResult.error }),
-                  is_error: true
-                }
-              ]
-            });
+            result = ToolResult.error(clientResult.error);
           } else {
             if (!clientResult.skipLlmResponse) {
               allSkip = false;
             }
-            let resultForLLM = clientResult.result;
-            if (typeof resultForLLM === "object" && resultForLLM !== null && "agentMessage" in resultForLLM) {
-              const { agentMessage, ...rest } = resultForLLM;
-              resultForLLM = { ...rest, label: agentMessage };
-            }
-            this.messages.push({
-              role: "user",
-              content: [
-                {
-                  type: "tool_result",
-                  tool_use_id: toolUseId,
-                  content: JSON.stringify(resultForLLM)
-                }
-              ]
-            });
+            result = ToolResult.fromClientResult(clientResult.result);
           }
+          this.pushToolExchange(
+            toolUseId,
+            autoTool.toolName,
+            autoTool.params,
+            result
+          );
         } catch {
           hasErrors = true;
           allSkip = false;
-          this.messages.push({
-            role: "assistant",
-            content: [
-              {
-                type: "tool_use",
-                id: toolUseId,
-                name: autoTool.toolName,
-                input: autoTool.params
-              }
-            ]
-          });
-          this.messages.push({
-            role: "user",
-            content: [
-              {
-                type: "tool_result",
-                tool_use_id: toolUseId,
-                content: JSON.stringify({
-                  error: "Auto-executed tool call was cancelled."
-                }),
-                is_error: true
-              }
-            ]
-          });
+          this.pushToolExchange(
+            toolUseId,
+            autoTool.toolName,
+            autoTool.params,
+            ToolResult.error("Auto-executed tool call was cancelled.")
+          );
         }
       }
       allAutoToolsSkipLlm = allSkip && !hasErrors;
@@ -502,7 +476,6 @@ ${skill.content}`
       return;
     }
     this.abortController = new AbortController();
-    this.isProcessing = true;
     let toolCallCounter = 0;
     let planRetryCount = 0;
     let streamRetryCount = 0;
@@ -510,19 +483,19 @@ ${skill.content}`
     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 assistantContent = [];
+        const accumulator = new StreamAccumulator();
+        const assistantContent = accumulator.blocks;
         const toolResults = [];
         const extraBlocks = [];
         let messagesCommittedByPlanTool = false;
-        let currentToolUse = null;
-        let currentTextContent = "";
-        let inTextBlock = false;
         const eagerTools = this.resolveToolDefinitions(this.toolNames);
         const activatedToolNames = this.lazyToolNames.filter(
           (name) => this.activatedLazyTools.has(name)
@@ -537,7 +510,8 @@ ${skill.content}`
         const defCtx = {
           resolvedSkills,
           plan: this.plan,
-          unloadedLazyTools
+          unloadedLazyTools,
+          lazyToolNames: this.lazyToolNames
         };
         const serverToolDefs = serverTools.map((t) => buildDefinition(t, defCtx)).filter((d) => d !== null);
         const allTools = [...serverToolDefs, ...eagerTools, ...activatedTools];
@@ -555,11 +529,14 @@ ${skill.content}`
         const stream = provider.createStream(
           {
             apiKey,
-            model: (models.find((m) => m.isDefault) || models[0]).name
+            model: getDefaultModel(models)?.name ?? ""
           },
           {
             systemPrompt,
-            messages: this.messages,
+            // 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
@@ -575,70 +552,42 @@ ${skill.content}`
                 this.lastDebugPayload = event.payload;
                 break;
               case "text_start":
-                inTextBlock = true;
-                currentTextContent = "";
+                accumulator.startText();
                 break;
-              case "text_delta":
-                if (inTextBlock) {
-                  const transformed = transformText(event.text);
-                  currentTextContent += transformed;
+              case "text_delta": {
+                const transformed = accumulator.pushTextDelta(event.text);
+                if (transformed !== null) {
                   send(peer, { type: "text_delta", content: transformed });
                 }
                 break;
+              }
               case "text_end":
-                if (inTextBlock && currentTextContent) {
-                  assistantContent.push({
-                    type: "text",
-                    text: currentTextContent
-                  });
-                }
-                currentTextContent = "";
-                inTextBlock = false;
+                accumulator.endText();
                 break;
               case "tool_use_start":
-                currentToolUse = {
-                  id: event.id,
-                  name: event.name,
-                  inputJson: ""
-                };
+                accumulator.startToolUse(event.id, event.name);
                 break;
               case "tool_use_delta":
-                if (currentToolUse) {
-                  currentToolUse.inputJson += event.partial_json;
-                }
+                accumulator.pushToolUseDelta(event.partial_json);
                 break;
-              case "tool_use_end":
-                if (currentToolUse) {
-                  let input;
-                  try {
-                    input = JSON.parse(currentToolUse.inputJson || "{}");
-                  } catch {
-                    input = {};
-                    assistantContent.push({
-                      type: "tool_use",
-                      id: currentToolUse.id,
-                      name: currentToolUse.name,
-                      input
-                    });
+              case "tool_use_end": {
+                const finished = accumulator.finishToolUse();
+                if (finished) {
+                  if (!finished.ok) {
                     toolResults.push({
                       type: "tool_result",
-                      tool_use_id: currentToolUse.id,
+                      tool_use_id: finished.id,
                       content: JSON.stringify({
                         error: "Your tool call produced malformed JSON input. Please try again."
                       }),
                       is_error: true
                     });
-                    currentToolUse = null;
                     break;
                   }
+                  const { id: toolUseId, name: toolName, input } = finished;
+                  const inputJson = finished.inputJson;
                   const callId = `tc_${toolCallCounter++}`;
-                  assistantContent.push({
-                    type: "tool_use",
-                    id: currentToolUse.id,
-                    name: currentToolUse.name,
-                    input
-                  });
-                  const toolCallKey = currentToolUse.name + ":" + currentToolUse.inputJson;
+                  const toolCallKey = toolName + ":" + inputJson;
                   if (toolCallKey === lastToolCallKey) {
                     consecutiveIdenticalCalls++;
                   } else {
@@ -648,159 +597,65 @@ ${skill.content}`
                   if (consecutiveIdenticalCalls > MAX_IDENTICAL_CALLS) {
                     toolResults.push({
                       type: "tool_result",
-                      tool_use_id: currentToolUse.id,
+                      tool_use_id: toolUseId,
                       content: JSON.stringify({
-                        error: `You have called "${currentToolUse.name}" ${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.`
+                        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
                     });
-                    currentToolUse = null;
                     break;
                   }
                   const matchedServerTool = serverTools.find(
-                    (t) => t.name === currentToolUse.name
+                    (t) => t.name === toolName
                   );
                   if (matchedServerTool) {
-                    if (matchedServerTool.isAvailable && !matchedServerTool.isAvailable(defCtx)) {
-                      toolResults.push({
-                        type: "tool_result",
-                        tool_use_id: currentToolUse.id,
-                        content: JSON.stringify({
-                          error: "This tool is not available right now."
-                        }),
-                        is_error: true
-                      });
-                      currentToolUse = null;
-                      break;
-                    }
-                    const handlerCtx = {
-                      toolUseId: currentToolUse.id,
-                      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) => {
-                        if (assistantContent.length) {
-                          this.messages.push({
-                            role: "assistant",
-                            content: [...assistantContent]
-                          });
-                          assistantContent.length = 0;
-                        }
-                        this.messages.push({
-                          role: "user",
-                          content: [toolResult]
-                        });
-                      },
-                      updateLastToolResult: (toolUseId, content) => {
-                        const lastMsg = this.messages[this.messages.length - 1];
-                        if (lastMsg.role === "user" && Array.isArray(lastMsg.content)) {
-                          const resultBlock = lastMsg.content.find(
-                            (b) => b.type === "tool_result" && b.tool_use_id === toolUseId
-                          );
-                          if (resultBlock && resultBlock.type === "tool_result") {
-                            resultBlock.content = content;
-                          }
-                        }
-                      },
-                      planStepHasWork: this.planStepHasWork,
-                      markPlanStepWork: () => {
-                        this.planStepHasWork = true;
-                      },
-                      resetPlanStepWork: () => {
-                        this.planStepHasWork = false;
-                      }
-                    };
-                    try {
-                      const coercedInput = {};
-                      for (const key of Object.keys(input)) {
-                        const value = input[key];
-                        if (typeof value === "string" && (value[0] === "[" || value[0] === "{")) {
-                          try {
-                            coercedInput[key] = JSON.parse(value);
-                          } catch {
-                            coercedInput[key] = value;
-                          }
-                        } else {
-                          coercedInput[key] = value;
-                        }
-                      }
-                      const parsed = matchedServerTool.inputSchema(defCtx).parse(coercedInput);
-                      const result = await matchedServerTool.handle(
-                        handlerCtx,
-                        parsed
-                      );
-                      toolResults.push(...result.toolResults);
-                      if (result.extraBlocks) {
-                        extraBlocks.push(...result.extraBlocks);
-                      }
-                      if (result.messagesCommitted) {
-                        messagesCommittedByPlanTool = true;
+                    const dispatch = await this.dispatchServerTool(
+                      matchedServerTool,
+                      {
+                        toolUseId,
+                        input,
+                        defCtx,
+                        resolvedSkills,
+                        peer,
+                        assistantContent
                       }
-                    } catch (e) {
-                      toolResults.push({
-                        type: "tool_result",
-                        tool_use_id: currentToolUse.id,
-                        content: JSON.stringify({
-                          error: `Invalid input: ${e.message}`
-                        }),
-                        is_error: true
-                      });
+                    );
+                    toolResults.push(...dispatch.toolResults);
+                    if (dispatch.extraBlocks) {
+                      extraBlocks.push(...dispatch.extraBlocks);
+                    }
+                    if (dispatch.messagesCommitted) {
+                      messagesCommittedByPlanTool = true;
                     }
-                    currentToolUse = null;
                     break;
                   }
-                  send(peer, {
-                    type: "tool_call",
-                    callId,
-                    tool: currentToolUse.name,
-                    params: input
-                  });
-                  try {
-                    const clientResult = await this.waitForToolResult(callId);
-                    if (clientResult.error) {
-                      toolResults.push({
-                        type: "tool_result",
-                        tool_use_id: currentToolUse.id,
-                        content: JSON.stringify({
-                          error: clientResult.error
-                        }),
-                        is_error: true
-                      });
-                    } else {
-                      let resultForLLM = clientResult.result;
-                      if (typeof resultForLLM === "object" && resultForLLM !== null && "agentMessage" in resultForLLM) {
-                        const { agentMessage, ...rest } = resultForLLM;
-                        resultForLLM = { ...rest, label: agentMessage };
-                      }
-                      toolResults.push({
-                        type: "tool_result",
-                        tool_use_id: currentToolUse.id,
-                        content: JSON.stringify(resultForLLM)
-                      });
-                      this.planStepHasWork = true;
-                    }
-                  } catch (error) {
+                  const validation = this.validateClientToolInput(
+                    toolName,
+                    input
+                  );
+                  if (!validation.ok && consecutiveValidationFailures < MAX_HIDDEN_VALIDATION_FAILURES) {
+                    consecutiveValidationFailures++;
                     toolResults.push({
                       type: "tool_result",
-                      tool_use_id: currentToolUse.id,
-                      content: JSON.stringify({
-                        error: error.message
-                      }),
+                      tool_use_id: toolUseId,
+                      content: JSON.stringify({ error: validation.error }),
                       is_error: true
                     });
+                    break;
                   }
-                  currentToolUse = null;
+                  consecutiveValidationFailures = 0;
+                  toolResults.push(
+                    ...await this.dispatchClientTool({
+                      toolUseId,
+                      toolName,
+                      callId,
+                      input,
+                      peer
+                    })
+                  );
                 }
                 break;
+              }
               case "reasoning_summary":
                 assistantContent.push({
                   type: "reasoning",
@@ -809,21 +664,13 @@ ${skill.content}`
                   encryptedContent: event.encryptedContent
                 });
                 break;
-              case "message_end":
-                if (event.inputTokens !== void 0 && event.outputTokens !== void 0) {
-                  const defaultModel = models.find((m) => m.isDefault) || models[0];
-                  send(peer, {
-                    type: "usage",
-                    usage: {
-                      inputTokens: event.inputTokens,
-                      outputTokens: event.outputTokens,
-                      cacheCreationInputTokens: event.cacheCreationInputTokens ?? 0,
-                      cacheReadInputTokens: event.cacheReadInputTokens ?? 0,
-                      pricing: defaultModel?.pricing ?? null
-                    }
-                  });
+              case "message_end": {
+                const usage = createUsageTurn(event, getDefaultModel(models));
+                if (usage) {
+                  send(peer, { type: "usage", usage });
                 }
                 break;
+              }
               case "error":
                 throw event.error;
             }
@@ -839,8 +686,8 @@ ${skill.content}`
             );
             continue;
           }
-          if (isRetryable && this.messages[this.messages.length - 1] === userMessage) {
-            this.messages.pop();
+          if (isRetryable && this.history.peekLast() === userMessage) {
+            this.history.popLast();
             console.error(
               "[blokkli agent] Transient stream error, retries exhausted:",
               streamError
@@ -858,17 +705,18 @@ ${skill.content}`
           this.planStepHasWork = false;
           continue;
         }
+        let assistantNames;
         if (assistantContent.length) {
-          this.messages.push({
-            role: "assistant",
-            content: assistantContent
-          });
+          const assistant = new AssistantMessage([...assistantContent]);
+          assistantNames = assistant.toolUseNames();
+          this.history.append(assistant);
         }
         if (toolResults.length) {
-          this.messages.push({
+          const relay = ToolRelayMessage.fromWire({
             role: "user",
             content: [...toolResults, ...extraBlocks]
-          });
+          }).withResolvedNames((id) => assistantNames?.get(id));
+          this.history.append(relay);
           planRetryCount = 0;
           streamRetryCount = 0;
         }
@@ -895,15 +743,6 @@ ${skill.content}`
     } finally {
       this.isProcessing = false;
       this.abortController = null;
-      this.unprunedMessages = structuredClone(this.messages);
-      pruneMessages(
-        this.messages,
-        KEEP_RECENT_TURNS,
-        this.buildToolMetadataMap()
-      );
-      if (this.loadedSkills.size > 0) {
-        this.reconcileLoadedSkills();
-      }
       this.sendConversationState(peer, authSecret);
     }
   }
@@ -922,53 +761,196 @@ ${skill.content}`
     });
   }
   /**
-   * Bug 3 fix: safely push a user message, merging with the last message
-   * if it's also a user message to avoid consecutive same-role messages.
+   * 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.
    */
-  safePushUserMessage(text) {
-    const lastMessage = this.messages[this.messages.length - 1];
-    if (lastMessage && lastMessage.role === "user") {
-      if (typeof lastMessage.content === "string") {
-        lastMessage.content = lastMessage.content + "\n" + text;
-      } else {
-        lastMessage.content.push({ type: "text", text });
+  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;
       }
-    } else {
-      this.messages.push({ role: "user", content: text });
-    }
+    };
   }
   /**
-   * Remove skills from loadedSkills whose text content has been pruned
-   * from the conversation messages.
+   * Dispatch a server-side tool: reject if unavailable, coerce + validate input,
+   * run the handler. Returns the blocks to merge into the turn's results.
    */
-  reconcileLoadedSkills() {
-    const presentSkills = /* @__PURE__ */ new Set();
-    for (const msg of this.messages) {
-      if (msg.role !== "user" || !Array.isArray(msg.content)) continue;
-      for (const block of msg.content) {
-        if (block.type === "skill") {
-          presentSkills.add(block.name);
-        }
-      }
+  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
+          }
+        ]
+      };
     }
-    for (const name of this.loadedSkills) {
-      if (!presentSkills.has(name)) {
-        this.loadedSkills.delete(name);
-      }
+    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
+          }
+        ]
+      };
     }
   }
   /**
-   * Build a map of tool name to pruning metadata from all known tools.
+   * 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).
    */
-  buildToolMetadataMap() {
-    const map = /* @__PURE__ */ new Map();
-    for (const name of [...this.toolNames, ...this.lazyToolNames]) {
-      const bundled = this.bundledToolMap.get(name);
-      if (bundled?.volatile) {
-        map.set(name, { volatile: true });
+  /**
+   * 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
+        }
+      ];
     }
-    return map;
+  }
+  /**
+   * 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(
@@ -980,21 +962,7 @@ ${skill.content}`
       this.getActivePlanContext(),
       this.loadedSkills
     ) : [];
-    const messages = this.messages.map((msg, i) => {
-      const entry = {
-        type: msg.role === "assistant" ? "agent" : "user",
-        seen: msg.content
-      };
-      const unpruned = this.unprunedMessages[i];
-      if (unpruned) {
-        const seenJson = JSON.stringify(msg.content);
-        const fullJson = JSON.stringify(unpruned.content);
-        if (seenJson !== fullJson) {
-          entry.full = unpruned.content;
-        }
-      }
-      return entry;
-    });
+    const messages = this.history.buildTranscriptMessages(this.volatileLookup());
     const tools = this.lastTools.map((t) => ({
       name: t.name,
       description: t.description,