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

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

@@ -0,0 +1,241 @@
+import {
+  ConversationMessage,
+  UserPromptMessage,
+  AssistantMessage,
+  ToolRelayMessage
+} from "../ConversationMessage/index.js";
+export class ConversationHistory {
+  /** Recent user turns kept uncompressed (age ceiling). */
+  static KEEP_RECENT_TURNS = 8;
+  /** Token budget for full tool-result content kept live (size ceiling). */
+  static DEFAULT_LIVE_TOKEN_BUDGET = 6e3;
+  /** User turns kept when projecting for persistence. */
+  static PERSISTENCE_KEEP_TURNS = 7;
+  messages = [];
+  get length() {
+    return this.messages.length;
+  }
+  // --------------------------------------------------------------------------
+  // Mutators (conversation construction — not pruning)
+  // --------------------------------------------------------------------------
+  append(message) {
+    this.messages.push(message);
+  }
+  /** Append a synthetic assistant `tool_use` + the matching tool-result relay. */
+  appendToolExchange(assistant, relay) {
+    this.messages.push(assistant);
+    this.messages.push(relay);
+  }
+  /**
+   * Append user text, merging into the last message when it is already a
+   * user-role message (the API rejects consecutive same-role messages).
+   */
+  mergeOrAppendUserText(text) {
+    const lastIndex = this.messages.length - 1;
+    const last = this.messages[lastIndex];
+    if (last instanceof UserPromptMessage) {
+      this.messages[lastIndex] = last.appendText(text);
+    } else if (last instanceof ToolRelayMessage) {
+      this.messages[lastIndex] = last.appendAux({ type: "text", text });
+    } else {
+      this.messages.push(new UserPromptMessage(text));
+    }
+  }
+  /**
+   * Replace one result in the last relay (a server tool finalising a
+   * placeholder it committed earlier — e.g. create_plan after approval).
+   */
+  replaceLastResult(toolUseId, result) {
+    const lastIndex = this.messages.length - 1;
+    const last = this.messages[lastIndex];
+    if (last instanceof ToolRelayMessage) {
+      this.messages[lastIndex] = last.replaceResult(toolUseId, result);
+    }
+  }
+  peekLast() {
+    return this.messages[this.messages.length - 1];
+  }
+  popLast() {
+    this.messages.pop();
+  }
+  /**
+   * Remove the Nth real user turn (0-based) and everything after it. Throws if
+   * the index is out of range.
+   */
+  truncateAtUserTurn(index) {
+    const starts = this.userTurnStartIndices();
+    const start = starts[index];
+    if (start === void 0) {
+      throw new Error(
+        `rollbackToUserMessageIndex ${index} out of range (only ${starts.length} real user turns)`
+      );
+    }
+    this.messages = this.messages.slice(0, start);
+  }
+  /** Replace the whole history from a persisted wire snapshot (restore). */
+  replaceAll(wire) {
+    const messages = wire.map((m) => ConversationMessage.fromWire(m));
+    for (let i = 0; i < messages.length; i++) {
+      const m = messages[i];
+      if (m instanceof ToolRelayMessage) {
+        const prev = messages[i - 1];
+        const names = prev instanceof AssistantMessage ? prev.toolUseNames() : void 0;
+        messages[i] = m.withResolvedNames((id) => names?.get(id));
+      }
+    }
+    this.messages = messages;
+  }
+  clear() {
+    this.messages = [];
+  }
+  // --------------------------------------------------------------------------
+  // Reads
+  // --------------------------------------------------------------------------
+  countUserTurns() {
+    return this.userTurnStartIndices().length;
+  }
+  /** Canonical messages as wire form — the "full" (uncompressed) view. */
+  toWireAll() {
+    return this.messages.map((m) => m.toWire());
+  }
+  /**
+   * Pure, deterministic projection of the conversation for the LLM. Returns a
+   * fresh `GenericMessage[]` exactly as long as the canonical history (1:1, so
+   * tool_use/tool_result pairing, turn indexing, and the cache-stable prefix
+   * are preserved). Never mutates canonical.
+   *
+   * Two ceilings combine (compress the union of both):
+   *  - age: user turns older than `keepRecentTurns` are compressed;
+   *  - size: tool-result rounds beyond `tokenBudget` (newest always kept full).
+   * Plus eager volatile staleness: a volatile query result with a later
+   * mutation collapses to `{ stale }` regardless of recency.
+   */
+  projectForLlm(isVolatile, opts = {}) {
+    const keepRecentTurns = opts.keepRecentTurns ?? ConversationHistory.KEEP_RECENT_TURNS;
+    const tokenBudget = opts.tokenBudget ?? ConversationHistory.DEFAULT_LIVE_TOKEN_BUDGET;
+    const staleToolUseIds = this.computeStaleToolUseIds(isVolatile);
+    const ageBoundary = this.ageCompressBoundary(keepRecentTurns);
+    const budgetBoundary = this.budgetCompressBoundary(
+      tokenBudget,
+      staleToolUseIds
+    );
+    const compressBefore = Math.max(ageBoundary, budgetBoundary);
+    return this.messages.map((message, i) => {
+      const old = i < compressBefore;
+      if (message instanceof AssistantMessage) {
+        return (old ? message.withPrunedToolUseInputs() : message).toWire();
+      }
+      if (message instanceof ToolRelayMessage) {
+        return message.project({ staleToolUseIds, compressBody: old, stripAux: old }).toWire();
+      }
+      return message.toWire();
+    });
+  }
+  /**
+   * Pure projection for persistence: trim to the last `keepTurns` user turns and
+   * aggressively compress (all tool results compressed, aux + old tool_use inputs
+   * stripped). No volatile metadata. Output is hashed + stored by the caller.
+   */
+  projectForPersistence(opts = {}) {
+    const keepTurns = opts.keepTurns ?? ConversationHistory.PERSISTENCE_KEEP_TURNS;
+    const starts = this.userTurnStartIndices();
+    const startIndex = starts.length > keepTurns ? starts[starts.length - keepTurns] ?? 0 : 0;
+    const trimmed = this.messages.slice(startIndex);
+    let lastTurnStart = 0;
+    for (let i = trimmed.length - 1; i >= 0; i--) {
+      if (trimmed[i] instanceof UserPromptMessage) {
+        lastTurnStart = i;
+        break;
+      }
+    }
+    const noStale = /* @__PURE__ */ new Set();
+    return trimmed.map((message, i) => {
+      const old = i < lastTurnStart;
+      if (message instanceof AssistantMessage) {
+        return (old ? message.withPrunedToolUseInputs() : message).toWire();
+      }
+      if (message instanceof ToolRelayMessage) {
+        return message.project({
+          staleToolUseIds: noStale,
+          compressBody: true,
+          stripAux: old
+        }).toWire();
+      }
+      return message.toWire();
+    });
+  }
+  /**
+   * Transcript rows: `seen` is the projected (compressed) content the LLM sees,
+   * `full` the canonical content — included only when it differs.
+   */
+  buildTranscriptMessages(isVolatile, opts = {}) {
+    const seen = this.projectForLlm(isVolatile, opts);
+    return this.messages.map((message, i) => {
+      const full = message.toWire();
+      const seenContent = seen[i].content;
+      const entry = {
+        type: full.role === "assistant" ? "agent" : "user",
+        seen: seenContent
+      };
+      if (JSON.stringify(seenContent) !== JSON.stringify(full.content)) {
+        entry.full = full.content;
+      }
+      return entry;
+    });
+  }
+  // --------------------------------------------------------------------------
+  // Internals
+  // --------------------------------------------------------------------------
+  userTurnStartIndices() {
+    const indices = [];
+    for (let i = 0; i < this.messages.length; i++) {
+      if (this.messages[i] instanceof UserPromptMessage) indices.push(i);
+    }
+    return indices;
+  }
+  /** Index before which messages are compressed by the age ceiling (0 = none). */
+  ageCompressBoundary(keepRecentTurns) {
+    const starts = this.userTurnStartIndices();
+    if (starts.length <= keepRecentTurns) return 0;
+    return starts[starts.length - keepRecentTurns] ?? 0;
+  }
+  /** Index before which messages are compressed by the token-budget ceiling. */
+  budgetCompressBoundary(tokenBudget, staleToolUseIds) {
+    let used = 0;
+    let seenNewest = false;
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const message = this.messages[i];
+      if (!(message instanceof ToolRelayMessage)) continue;
+      const size = message.projectedTokens(staleToolUseIds);
+      if (!seenNewest) {
+        seenNewest = true;
+        used += size;
+        continue;
+      }
+      used += size;
+      if (used > tokenBudget) return i + 1;
+    }
+    return 0;
+  }
+  /**
+   * Tool-use ids of volatile query results that a later mutation made stale.
+   * Single backward scan tracking whether a mutation has been seen yet.
+   */
+  computeStaleToolUseIds(isVolatile) {
+    const stale = /* @__PURE__ */ new Set();
+    let seenMutationAfter = false;
+    for (let i = this.messages.length - 1; i >= 0; i--) {
+      const message = this.messages[i];
+      if (!(message instanceof ToolRelayMessage)) continue;
+      for (const entry of message.entries) {
+        if (seenMutationAfter && isVolatile(entry.toolName)) {
+          stale.add(entry.toolUseId);
+        }
+      }
+      if (message.entries.some((e) => e.result.isMutationSuccess())) {
+        seenMutationAfter = true;
+      }
+    }
+    return stale;
+  }
+}

package/dist/modules/agent/runtime/server/classes/ConversationMessage/index.d.ts

@@ -0,0 +1,102 @@
+import type { GenericMessage, GenericContentBlock, GenericTextBlock, GenericSkillBlock } from '../../../shared/types.js';
+import { ToolResult } from '../../../shared/toolResult.js';
+/**
+ * Typed, OOP representation of one conversation message.
+ *
+ * `Session` keeps an immutable list of these as the single source of truth.
+ * They are an internal server representation: every external consumer (the LLM
+ * providers, persistence, the transcript, the state hash) keeps consuming the
+ * plain `GenericMessage` wire shape produced by {@link toWire}. The pruning that
+ * used to mutate the message array is now a pure projection (see
+ * `ConversationHistory`) that compresses *copies* produced by these classes.
+ *
+ * Message kind is explicit (`kind`) rather than inferred from content shape,
+ * replacing the old `isToolResultOnly` / `countUserTurns` heuristics.
+ */
+export declare abstract class ConversationMessage {
+    abstract readonly kind: 'userPrompt' | 'assistant' | 'toolRelay';
+    abstract toWire(): GenericMessage;
+    /**
+     * Rehydrate a message from its wire form (persistence restore). Tool names on
+     * relay results are NOT resolved here (a single message lacks the preceding
+     * assistant); `ConversationHistory.replaceAll` resolves them.
+     */
+    static fromWire(msg: GenericMessage): ConversationMessage;
+}
+/**
+ * A genuine user turn — the prompt text, optionally preceded by auto-loaded
+ * skill blocks. Never compressed (a prompt's text is content, not a tool result),
+ * so prompt text can never be stripped and the content array can never be emptied.
+ */
+export declare class UserPromptMessage extends ConversationMessage {
+    private readonly content;
+    readonly kind: "userPrompt";
+    constructor(content: string | GenericContentBlock[]);
+    toWire(): GenericMessage;
+    /** Pure: a copy with `text` merged in (string concat or appended text block). */
+    appendText(text: string): UserPromptMessage;
+}
+/**
+ * An assistant turn: an ordered list of text / reasoning / tool_use blocks
+ * (or, rarely, a plain string when rehydrated). The content union is preserved
+ * verbatim so projection re-serialises byte-identically.
+ */
+export declare class AssistantMessage extends ConversationMessage {
+    private readonly content;
+    readonly kind: "assistant";
+    constructor(content: string | GenericContentBlock[]);
+    toWire(): GenericMessage;
+    /** Map of `tool_use` id → tool name, for resolving relay tool names. */
+    toolUseNames(): Map<string, string>;
+    /**
+     * Pure: a copy with every `tool_use` input collapsed to `{ _pruned: true }`.
+     * `text` / `reasoning` / `skill` blocks are left untouched.
+     */
+    withPrunedToolUseInputs(): AssistantMessage;
+}
+/** One tool result inside a relay, with the tool name that produced it. */
+export type ToolRelayEntry = {
+    toolUseId: string;
+    /** Resolved from the preceding assistant's `tool_use`; drives volatile checks. */
+    toolName: string | undefined;
+    result: ToolResult;
+};
+/**
+ * A tool-result relay: `{ role: 'user', content: [tool_result, ...auxBlocks] }`.
+ * The protocol encodes tool results as user-role messages; this class makes that
+ * explicit. Carries the resolved tool name per result so the projection needs no
+ * back-scan.
+ */
+export declare class ToolRelayMessage extends ConversationMessage {
+    private readonly results;
+    private readonly auxBlocks;
+    readonly kind: "toolRelay";
+    constructor(results: ToolRelayEntry[], auxBlocks?: (GenericTextBlock | GenericSkillBlock)[]);
+    static fromWire(msg: GenericMessage): ToolRelayMessage;
+    get entries(): readonly ToolRelayEntry[];
+    toWire(): GenericMessage;
+    /** Estimated token cost of the full (uncompressed) tool-result content. */
+    estimatedTokens(): number;
+    /**
+     * Estimated tokens once the given results are marked stale — used by the
+     * budget walk so a large stale result doesn't consume budget (the
+     * volatile/staleness decision logically precedes the size ceiling).
+     */
+    projectedTokens(staleToolUseIds: Set<string>): number;
+    /** Pure: a copy with an auxiliary text/skill block appended. */
+    appendAux(block: GenericTextBlock | GenericSkillBlock): ToolRelayMessage;
+    /**
+     * Pure projection: per-result, stale results (by tool_use id) collapse to
+     * `{ stale }`, otherwise compress the body when `compressBody`. Aux blocks are
+     * dropped when `stripAux`.
+     */
+    project(opts: {
+        staleToolUseIds: Set<string>;
+        compressBody: boolean;
+        stripAux: boolean;
+    }): ToolRelayMessage;
+    /** Pure: a copy with one result replaced (create_plan post-approval swap). */
+    replaceResult(toolUseId: string, result: ToolResult): ToolRelayMessage;
+    /** Pure: a copy with tool names resolved via the given lookup (rehydration). */
+    withResolvedNames(resolve: (toolUseId: string) => string | undefined): ToolRelayMessage;
+}

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

@@ -0,0 +1,156 @@
+import { ToolResult } from "../../../shared/toolResult.js";
+export class ConversationMessage {
+  /**
+   * Rehydrate a message from its wire form (persistence restore). Tool names on
+   * relay results are NOT resolved here (a single message lacks the preceding
+   * assistant); `ConversationHistory.replaceAll` resolves them.
+   */
+  static fromWire(msg) {
+    if (msg.role === "assistant") {
+      return new AssistantMessage(msg.content);
+    }
+    if (Array.isArray(msg.content) && msg.content.some((b) => b.type === "tool_result")) {
+      return ToolRelayMessage.fromWire(msg);
+    }
+    return new UserPromptMessage(msg.content);
+  }
+}
+export class UserPromptMessage extends ConversationMessage {
+  constructor(content) {
+    super();
+    this.content = content;
+  }
+  kind = "userPrompt";
+  toWire() {
+    return { role: "user", content: this.content };
+  }
+  /** Pure: a copy with `text` merged in (string concat or appended text block). */
+  appendText(text) {
+    if (typeof this.content === "string") {
+      return new UserPromptMessage(this.content + "\n" + text);
+    }
+    return new UserPromptMessage([...this.content, { type: "text", text }]);
+  }
+}
+export class AssistantMessage extends ConversationMessage {
+  constructor(content) {
+    super();
+    this.content = content;
+  }
+  kind = "assistant";
+  toWire() {
+    return { role: "assistant", content: this.content };
+  }
+  /** Map of `tool_use` id → tool name, for resolving relay tool names. */
+  toolUseNames() {
+    const map = /* @__PURE__ */ new Map();
+    if (Array.isArray(this.content)) {
+      for (const block of this.content) {
+        if (block.type === "tool_use") map.set(block.id, block.name);
+      }
+    }
+    return map;
+  }
+  /**
+   * Pure: a copy with every `tool_use` input collapsed to `{ _pruned: true }`.
+   * `text` / `reasoning` / `skill` blocks are left untouched.
+   */
+  withPrunedToolUseInputs() {
+    if (!Array.isArray(this.content)) return this;
+    const blocks = this.content.map(
+      (block) => block.type === "tool_use" ? { ...block, input: { _pruned: true } } : block
+    );
+    return new AssistantMessage(blocks);
+  }
+}
+export class ToolRelayMessage extends ConversationMessage {
+  constructor(results, auxBlocks = []) {
+    super();
+    this.results = results;
+    this.auxBlocks = auxBlocks;
+  }
+  kind = "toolRelay";
+  static fromWire(msg) {
+    const content = Array.isArray(msg.content) ? msg.content : [];
+    const results = [];
+    const auxBlocks = [];
+    for (const block of content) {
+      if (block.type === "tool_result") {
+        results.push({
+          toolUseId: block.tool_use_id,
+          toolName: void 0,
+          result: ToolResult.fromWire(block.content, block.is_error)
+        });
+      } else if (block.type === "text" || block.type === "skill") {
+        auxBlocks.push(block);
+      }
+    }
+    return new ToolRelayMessage(results, auxBlocks);
+  }
+  get entries() {
+    return this.results;
+  }
+  toWire() {
+    const content = this.results.map((entry) => {
+      const block = {
+        type: "tool_result",
+        tool_use_id: entry.toolUseId,
+        content: entry.result.toWire()
+      };
+      if (entry.result.isErrorResult()) block.is_error = true;
+      return block;
+    });
+    return { role: "user", content: [...content, ...this.auxBlocks] };
+  }
+  /** Estimated token cost of the full (uncompressed) tool-result content. */
+  estimatedTokens() {
+    return this.results.reduce((sum, e) => sum + e.result.estimatedTokens(), 0);
+  }
+  /**
+   * Estimated tokens once the given results are marked stale — used by the
+   * budget walk so a large stale result doesn't consume budget (the
+   * volatile/staleness decision logically precedes the size ceiling).
+   */
+  projectedTokens(staleToolUseIds) {
+    return this.results.reduce((sum, e) => {
+      const r = staleToolUseIds.has(e.toolUseId) ? e.result.stale() : e.result;
+      return sum + r.estimatedTokens();
+    }, 0);
+  }
+  /** Pure: a copy with an auxiliary text/skill block appended. */
+  appendAux(block) {
+    return new ToolRelayMessage(this.results, [...this.auxBlocks, block]);
+  }
+  /**
+   * Pure projection: per-result, stale results (by tool_use id) collapse to
+   * `{ stale }`, otherwise compress the body when `compressBody`. Aux blocks are
+   * dropped when `stripAux`.
+   */
+  project(opts) {
+    const results = this.results.map((entry) => {
+      let result = entry.result;
+      if (opts.staleToolUseIds.has(entry.toolUseId)) {
+        result = result.stale();
+      } else if (opts.compressBody) {
+        result = result.compressed();
+      }
+      return result === entry.result ? entry : { ...entry, result };
+    });
+    return new ToolRelayMessage(results, opts.stripAux ? [] : this.auxBlocks);
+  }
+  /** Pure: a copy with one result replaced (create_plan post-approval swap). */
+  replaceResult(toolUseId, result) {
+    const results = this.results.map(
+      (entry) => entry.toolUseId === toolUseId ? { ...entry, result } : entry
+    );
+    return new ToolRelayMessage(results, this.auxBlocks);
+  }
+  /** Pure: a copy with tool names resolved via the given lookup (rehydration). */
+  withResolvedNames(resolve) {
+    const results = this.results.map((entry) => ({
+      ...entry,
+      toolName: entry.toolName ?? resolve(entry.toolUseId)
+    }));
+    return new ToolRelayMessage(results, this.auxBlocks);
+  }
+}

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

@@ -1,8 +1,9 @@
 import type { Peer } from 'crossws';
-import type { PageContext, ClientToolDefinition, ServerToolMetadata, ConversationStateSnapshot, GenericMessage } from '../shared/types.js';
-import type { ServerPlan } from './server-tools/index.js';
+import type { PageContext, ClientToolDefinition, ServerToolMetadata, ConversationStateSnapshot } from '../../../shared/types.js';
+import type { ServerPlan } from '../../server-tools/index.js';
 export declare class Session {
-    messages: GenericMessage[];
+    /** The single, immutable source of truth for the conversation. */
+    private history;
     pendingToolCalls: Map<string, {
         resolve: (result: {
             result: unknown;
@@ -31,8 +32,6 @@ export declare class Session {
     pendingPlanApproval: {
         resolve: (approved: boolean) => void;
     } | null;
-    /** Pre-pruned messages snapshot for transcript (captured before pruneMessages) */
-    private unprunedMessages;
     /** Last generic tool definitions for transcript */
     private lastTools;
     /** Last raw request payload for transcript (dev only) */
@@ -64,7 +63,13 @@ export declare class Session {
     }[], autoExecuteTools?: {
         toolName: string;
         params: Record<string, unknown>;
-    }[]): void;
+    }[], rollbackToUserMessageIndex?: number): void;
+    /**
+     * 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.
+     */
+    private truncateAtUserMessage;
     resolveToolResult(callId: string, result: {
         result: unknown;
         error?: string;
@@ -111,18 +116,45 @@ export declare class Session {
     private runAgentLoop;
     private waitForToolResult;
     /**
-     * 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.
      */
-    private safePushUserMessage;
+    private buildServerToolContext;
+    /**
+     * Dispatch a server-side tool: reject if unavailable, coerce + validate input,
+     * run the handler. Returns the blocks to merge into the turn's results.
+     */
+    private dispatchServerTool;
+    /**
+     * 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).
+     */
+    private validateClientToolInput;
+    private dispatchClientTool;
     /**
-     * Remove skills from loadedSkills whose text content has been pruned
-     * from the conversation messages.
+     * 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.
      */
-    private reconcileLoadedSkills;
+    private pushToolExchange;
+    /**
+     * 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.
+     */
+    private safePushUserMessage;
     /**
-     * Build a map of tool name to pruning metadata from all known tools.
+     * 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.
      */
-    private buildToolMetadataMap;
+    private volatileLookup;
     private buildTranscript;
 }