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

package/dist/modules/agent/runtime/app/types/index.d.ts

@@ -5,10 +5,7 @@ import { type UsageTurn } from '#blokkli/agent/shared/types';
 import { z } from 'zod';
 import type { Component } from 'vue';
 import type { AgentToolName, AgentSkillName, AgentToolMap } from '#blokkli-build/agent-client';
-/**
- * Translation function type (matches $t from BlokkliApp).
- */
-export type TranslationFunction = (key: string, defaultValue: string) => string;
+import type { TextProvider } from '#blokkli/editor/providers/texts';
 /**
  * A host entity (parent of a block).
  * Used consistently across tools for specifying block locations.
@@ -171,7 +168,7 @@ export type McpToolDefinition<TParamsSchema extends z.ZodType = z.ZodType, TResu
      * Returns the label to display while the tool is executing.
      * This is shown before the tool completes and provides its final label.
      */
-    label: ($t: TranslationFunction) => string;
+    label: ($t: TextProvider) => string;
     /** Zod schema for input parameters */
     paramsSchema: TParamsSchema;
     /** Zod schema for the result */
@@ -356,13 +353,32 @@ declare const userConversationItemSchema: z.ZodObject<{
         id: z.ZodString;
         content: z.ZodString;
         format: z.ZodEnum<{
-            html: "html";
             code: "code";
+            html: "html";
             markdown: "markdown";
             csv: "csv";
             plaintext: "plaintext";
         }>;
     }, z.core.$strip>>>;
+    historyIndexAtSend: z.ZodOptional<z.ZodNumber>;
+    historySignatureAtSend: z.ZodOptional<z.ZodString>;
+    sendContext: z.ZodOptional<z.ZodObject<{
+        promptId: z.ZodOptional<z.ZodString>;
+        serverPrompt: z.ZodOptional<z.ZodString>;
+        selectedUuids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        autoLoadTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        autoLoadSkills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        preSeededResults: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            toolName: z.ZodString;
+            params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            result: z.ZodUnknown;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
+        autoExecuteTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            toolName: z.ZodString;
+            params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
  * An assistant text message in the conversation history.
@@ -390,6 +406,19 @@ declare const toolConversationItemSchema: z.ZodObject<{
         error: "error";
     }>;
 }, z.core.$strip>;
+/**
+ * Names of server-side tools, plus `plan_completed` which is synthesized
+ * client-side (not a wire value). Single source for the conversation item and
+ * the components that render it.
+ */
+export declare const serverToolNameSchema: z.ZodEnum<{
+    load_skills: "load_skills";
+    load_tools: "load_tools";
+    create_plan: "create_plan";
+    complete_plan_step: "complete_plan_step";
+    plan_completed: "plan_completed";
+}>;
+export type ServerToolName = z.infer<typeof serverToolNameSchema>;
 /**
  * A server-side tool call result in the conversation history.
  */
@@ -429,13 +458,32 @@ export declare const conversationItemSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
         id: z.ZodString;
         content: z.ZodString;
         format: z.ZodEnum<{
-            html: "html";
             code: "code";
+            html: "html";
             markdown: "markdown";
             csv: "csv";
             plaintext: "plaintext";
         }>;
     }, z.core.$strip>>>;
+    historyIndexAtSend: z.ZodOptional<z.ZodNumber>;
+    historySignatureAtSend: z.ZodOptional<z.ZodString>;
+    sendContext: z.ZodOptional<z.ZodObject<{
+        promptId: z.ZodOptional<z.ZodString>;
+        serverPrompt: z.ZodOptional<z.ZodString>;
+        selectedUuids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        autoLoadTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        autoLoadSkills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        preSeededResults: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            toolName: z.ZodString;
+            params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            result: z.ZodUnknown;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
+        autoExecuteTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            toolName: z.ZodString;
+            params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     id: z.ZodString;
     timestamp: z.ZodNumber;

package/dist/modules/agent/runtime/app/types/index.js

@@ -16,7 +16,53 @@ const userConversationItemSchema = conversationItemBase.extend({
       content: z.string(),
       format: z.enum(["plaintext", "markdown", "html", "csv", "code"])
     })
-  ).optional()
+  ).optional(),
+  /**
+   * Editor history index at the moment this message was sent. Used by
+   * retry/edit to restore the editor state before re-running the prompt.
+   * Optional for back-compat with conversations persisted before this field
+   * existed.
+   */
+  historyIndexAtSend: z.number().optional(),
+  /**
+   * Identity of the mutation at `historyIndexAtSend` when the snapshot was
+   * taken. Compared against the current mutation at that index to detect
+   * staleness — if the user manually undid + re-mutated, the snapshot is no
+   * longer reachable and retry/edit must be disabled.
+   */
+  historySignatureAtSend: z.string().optional(),
+  /**
+   * Original send parameters captured so retry produces byte-identical
+   * execution — important for prompt-definition-driven sends where the
+   * displayed text is a friendly label but the real work was driven by
+   * `selectedUuids`, pre-computed tool results, auto-executed tools, and
+   * auto-loaded tools/skills.
+   *
+   * Retry replays this context as-is. Edit discards `preSeededResults` and
+   * `autoExecuteTools` (the intent has changed) but preserves selection,
+   * tools, and skills — the edited prompt runs through a normal LLM round.
+   */
+  sendContext: z.object({
+    promptId: z.string().optional(),
+    serverPrompt: z.string().optional(),
+    selectedUuids: z.array(z.string()).optional(),
+    autoLoadTools: z.array(z.string()).optional(),
+    autoLoadSkills: z.array(z.string()).optional(),
+    preSeededResults: z.array(
+      z.object({
+        toolName: z.string(),
+        params: z.record(z.string(), z.unknown()),
+        result: z.unknown(),
+        label: z.string()
+      })
+    ).optional(),
+    autoExecuteTools: z.array(
+      z.object({
+        toolName: z.string(),
+        params: z.record(z.string(), z.unknown())
+      })
+    ).optional()
+  }).optional()
 });
 const assistantConversationItemSchema = conversationItemBase.extend({
   type: z.literal("assistant"),
@@ -29,15 +75,16 @@ const toolConversationItemSchema = conversationItemBase.extend({
   label: z.string(),
   status: z.enum(["active", "success", "error"])
 });
+export const serverToolNameSchema = z.enum([
+  "load_skills",
+  "load_tools",
+  "create_plan",
+  "complete_plan_step",
+  "plan_completed"
+]);
 const serverToolConversationItemSchema = conversationItemBase.extend({
   type: z.literal("server_tool"),
-  tool: z.enum([
-    "load_skills",
-    "load_tools",
-    "create_plan",
-    "complete_plan_step",
-    "plan_completed"
-  ]),
+  tool: serverToolNameSchema,
   label: z.string()
 });
 const errorConversationItemSchema = conversationItemBase.extend({

package/dist/modules/agent/runtime/server/agent.js

@@ -1,7 +1,7 @@
 import { defineWebSocketHandler, useRuntimeConfig } from "#imports";
 import { clientMessageSchema } from "../shared/types.js";
-import { SessionManager } from "./SessionManager.js";
-import { send } from "./helpers.js";
+import { SessionManager } from "./classes/SessionManager/index.js";
+import { send } from "./helpers/socket.js";
 import { toolDefinitions } from "#blokkli-build/agent-server";
 const sessionManager = new SessionManager(toolDefinitions);
 const config = useRuntimeConfig();
@@ -90,7 +90,8 @@ export default defineWebSocketHandler({
             data.autoLoadTools,
             data.autoLoadSkills,
             data.preSeededResults,
-            data.autoExecuteTools
+            data.autoExecuteTools,
+            data.rollbackToUserMessageIndex
           );
           break;
         case "tool_result":

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

@@ -0,0 +1,93 @@
+import type { GenericMessage, TranscriptMessage } from '../../../shared/types.js';
+import type { ToolResult } from '../../../shared/toolResult.js';
+import { ConversationMessage, AssistantMessage, ToolRelayMessage } from '../ConversationMessage/index.js';
+/** Looks up whether a tool's results go stale after a mutation. */
+export type VolatileLookup = (toolName: string | undefined) => boolean;
+export type LiveProjectionOptions = {
+    keepRecentTurns?: number;
+    tokenBudget?: number;
+};
+/**
+ * The single, append-only source of truth for a conversation.
+ *
+ * Canonical messages are never mutated for pruning — the views fed to the LLM,
+ * persistence, and the transcript are produced by **pure, deterministic**
+ * projections that compress copies. This replaces the old in-place pruning of
+ * `Session.messages` (and its `unprunedMessages` snapshot side-channel).
+ *
+ * The mutators here represent legitimate conversation construction (append a
+ * turn, merge a system note, finalise a placeholder, rollback, restore); none
+ * of them is pruning.
+ */
+export declare class ConversationHistory {
+    /** Recent user turns kept uncompressed (age ceiling). */
+    static readonly KEEP_RECENT_TURNS = 8;
+    /** Token budget for full tool-result content kept live (size ceiling). */
+    static readonly DEFAULT_LIVE_TOKEN_BUDGET = 6000;
+    /** User turns kept when projecting for persistence. */
+    static readonly PERSISTENCE_KEEP_TURNS = 7;
+    private messages;
+    get length(): number;
+    append(message: ConversationMessage): void;
+    /** Append a synthetic assistant `tool_use` + the matching tool-result relay. */
+    appendToolExchange(assistant: AssistantMessage, relay: ToolRelayMessage): void;
+    /**
+     * 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: string): void;
+    /**
+     * Replace one result in the last relay (a server tool finalising a
+     * placeholder it committed earlier — e.g. create_plan after approval).
+     */
+    replaceLastResult(toolUseId: string, result: ToolResult): void;
+    peekLast(): ConversationMessage | undefined;
+    popLast(): void;
+    /**
+     * Remove the Nth real user turn (0-based) and everything after it. Throws if
+     * the index is out of range.
+     */
+    truncateAtUserTurn(index: number): void;
+    /** Replace the whole history from a persisted wire snapshot (restore). */
+    replaceAll(wire: GenericMessage[]): void;
+    clear(): void;
+    countUserTurns(): number;
+    /** Canonical messages as wire form — the "full" (uncompressed) view. */
+    toWireAll(): GenericMessage[];
+    /**
+     * 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: VolatileLookup, opts?: LiveProjectionOptions): GenericMessage[];
+    /**
+     * 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?: {
+        keepTurns?: number;
+    }): GenericMessage[];
+    /**
+     * Transcript rows: `seen` is the projected (compressed) content the LLM sees,
+     * `full` the canonical content — included only when it differs.
+     */
+    buildTranscriptMessages(isVolatile: VolatileLookup, opts?: LiveProjectionOptions): TranscriptMessage[];
+    private userTurnStartIndices;
+    /** Index before which messages are compressed by the age ceiling (0 = none). */
+    private ageCompressBoundary;
+    /** Index before which messages are compressed by the token-budget ceiling. */
+    private budgetCompressBoundary;
+    /**
+     * Tool-use ids of volatile query results that a later mutation made stale.
+     * Single backward scan tracking whether a mutation has been seen yet.
+     */
+    private computeStaleToolUseIds;
+}

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;
+}