@revenexx/editor 0.1.0

package/dist/modules/agent/runtime/server/system-prompts/types.d.ts

@@ -0,0 +1,49 @@
+import type { PageContext, EditMode } from '../../shared/types.js';
+import type { ResolvedSkill } from '../skills/types.js';
+export type ActivePlanContext = {
+    title: string;
+    totalSteps: number;
+    completedSteps: number;
+    currentStep: {
+        label: string;
+        description: string;
+    };
+    remainingSteps: string[];
+};
+export type SystemPromptContext = {
+    pageContext: PageContext;
+    resolvedSkills: ResolvedSkill[];
+    lazyTools: {
+        name: string;
+        description: string;
+    }[];
+    isDebugMode: boolean;
+    activePlan?: ActivePlanContext;
+    loadedSkills: ReadonlySet<string>;
+};
+export type SystemPromptDefinition = {
+    id: string;
+    title: string;
+    weight: number;
+    modes?: EditMode[];
+    /**
+     * Cache group for prompt caching optimization.
+     * - 'static': Content never changes (cached indefinitely within TTL).
+     * - 'per-page': Content is stable across turns within a conversation (cached per page context).
+     * - Omit for per-turn content that changes every turn (e.g. plan progress).
+     *
+     * Prompts are sorted by cache group (static → per-page → per-turn), then by weight.
+     * This ensures stable prefixes for both Anthropic (explicit breakpoints) and OpenAI (automatic prefix caching).
+     */
+    cacheGroup?: 'static' | 'per-page';
+    getPrompt: (context: Readonly<SystemPromptContext>) => string | null;
+};
+/**
+ * A single block in the structured system prompt.
+ * Providers use cacheHint to apply provider-specific caching strategies.
+ */
+export type SystemPromptBlock = {
+    text: string;
+    /** When set, signals that everything up to and including this block can be cached. */
+    cacheHint?: 'ephemeral';
+};

package/dist/modules/agent/runtime/server/templates/defineStreamTemplate.d.ts

@@ -0,0 +1,21 @@
+import type { StreamTemplateDefinition } from './types.js';
+/**
+ * Define a stream template.
+ *
+ * Templates provide the system prompt and user message for the streaming
+ * sub-agent that performs text rewrites. The optional `defaultInstructions`
+ * field is appended to the system prompt only when no skill provides
+ * context for this template.
+ *
+ * @example
+ * ```ts
+ * export default defineStreamTemplate<{ instruction: string }>({
+ *   name: 'rewrite',
+ *   build: (params, fields) => ({
+ *     systemPrompt: `You are a text editing assistant.\n\n${buildOutputFormatBlock(fields)}`,
+ *     userMessage: params.instruction,
+ *   }),
+ * })
+ * ```
+ */
+export declare function defineStreamTemplate<TParams>(definition: StreamTemplateDefinition<TParams>): StreamTemplateDefinition<TParams>;

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

@@ -0,0 +1,3 @@
+export function defineStreamTemplate(definition) {
+  return definition;
+}

package/dist/modules/agent/runtime/server/templates/definitions/fixReadability.d.ts

@@ -0,0 +1,26 @@
+type FixReadabilityIssue = {
+    fieldIndex: number;
+    text: string;
+    impact: string;
+    score: number;
+};
+type FixReadabilityRetryField = {
+    fieldIndex: number;
+    fieldLabel: string;
+    originalValue: string;
+    previousAttempt: string;
+    score?: number;
+};
+type FixReadabilityParams = {
+    issues: FixReadabilityIssue[];
+    scoreLabel?: string;
+    scoreReference?: string;
+    retryFields?: FixReadabilityRetryField[];
+    passingFields?: Array<{
+        fieldLabel: string;
+        value: string;
+        score?: number;
+    }>;
+};
+declare const _default: import("..").StreamTemplateDefinition<FixReadabilityParams>;
+export default _default;

package/dist/modules/agent/runtime/server/templates/definitions/fixReadability.js

@@ -0,0 +1,84 @@
+import { defineStreamTemplate } from "../defineStreamTemplate.js";
+import { buildOutputFormatBlock } from "../utils.js";
+export default defineStreamTemplate({
+  name: "fix_readability",
+  defaultInstructions: `## How to Fix
+
+- Break long sentences into shorter ones
+- Replace complex or uncommon words with simpler alternatives
+- Reduce the number of words per sentence
+- Maintain the original meaning, tone, and information`,
+  build: (params, fields) => {
+    const label = params.scoreLabel || "score";
+    const issueList = params.issues.map((issue) => {
+      return `- Field ${issue.fieldIndex}: "${issue.text}" [impact: ${issue.impact}, ${label}: ${issue.score}]`;
+    }).join("\n");
+    let retryBlock = "";
+    if (params.retryFields && params.retryFields.length > 0) {
+      const parts = ["## Previous Attempt", ""];
+      if (params.passingFields && params.passingFields.length > 0) {
+        parts.push(
+          "The following fields were already improved and now have good readability:"
+        );
+        for (const p of params.passingFields) {
+          const truncated = p.value.length > 200 ? p.value.slice(0, 200) + "..." : p.value;
+          const scoreStr = p.score != null ? ` (${label}: ${Math.round(p.score)})` : "";
+          parts.push(`- "${p.fieldLabel}": "${truncated}"${scoreStr}`);
+        }
+        parts.push("");
+      }
+      parts.push(
+        "The following fields still have readability issues after your previous rewrite:",
+        ""
+      );
+      for (const rf of params.retryFields) {
+        const origTruncated = rf.originalValue.length > 500 ? rf.originalValue.slice(0, 500) + "..." : rf.originalValue;
+        const prevTruncated = rf.previousAttempt.length > 500 ? rf.previousAttempt.slice(0, 500) + "..." : rf.previousAttempt;
+        parts.push(`- Field ${rf.fieldIndex} ("${rf.fieldLabel}"):`);
+        parts.push(`  Original text: "${origTruncated}"`);
+        parts.push(`  Your previous rewrite: "${prevTruncated}"`);
+        const fieldIssues = params.issues.filter(
+          (i) => i.fieldIndex === rf.fieldIndex
+        );
+        if (fieldIssues.length > 0) {
+          parts.push("  Remaining issues:");
+          for (const issue of fieldIssues) {
+            parts.push(
+              `    - "${issue.text}" [impact: ${issue.impact}, ${label}: ${issue.score}]`
+            );
+          }
+        }
+        parts.push("");
+      }
+      parts.push("Try a different approach:");
+      parts.push("- Use shorter sentences (max 10-12 words per sentence)");
+      parts.push("- Replace complex or uncommon words with simple alternatives");
+      parts.push("- Break compound sentences into multiple simple ones");
+      retryBlock = "\n" + parts.join("\n") + "\n";
+    }
+    const scoreReference = params.scoreReference || "";
+    const systemPrompt = `You are a text editing assistant specialized in improving readability.
+
+## Task
+
+Fix ONLY the specific text segments listed below. Do NOT change any other text.
+
+## Flagged Readability Issues
+
+${issueList}
+${retryBlock}
+${scoreReference}
+
+## Important
+
+- ONLY modify the text segments listed above. Leave everything else untouched.
+- Use SEARCH/REPLACE mode. The search text should match or contain the flagged segment.
+- If a flagged segment spans an entire field, you may use FULL mode for that field.
+
+${buildOutputFormatBlock(fields)}`;
+    return {
+      systemPrompt,
+      userMessage: "Fix ONLY the flagged readability issues listed above. Do not change any other text."
+    };
+  }
+});

package/dist/modules/agent/runtime/server/templates/definitions/generateContent.d.ts

@@ -0,0 +1,6 @@
+type GenerateContentParams = {
+    instruction: string;
+    context?: string;
+};
+declare const _default: import("..").StreamTemplateDefinition<GenerateContentParams>;
+export default _default;

package/dist/modules/agent/runtime/server/templates/definitions/generateContent.js

@@ -0,0 +1,29 @@
+import { defineStreamTemplate } from "../defineStreamTemplate.js";
+import { buildOutputFormatBlock } from "../utils.js";
+export default defineStreamTemplate({
+  name: "generate_content",
+  defaultInstructions: `- Match the tone and style of any existing content on the page.
+- For HTML fields: use appropriate HTML structure (paragraphs, headings, lists) as needed.
+- For plain text fields: output plain text only, no HTML.`,
+  build: (params, fields) => {
+    let contextBlock = "";
+    if (params.context) {
+      contextBlock = `
+## Page Context
+
+${params.context}
+`;
+    }
+    const systemPrompt = `You are a content writing assistant. Your task is to write new content for text fields according to the user's instruction.
+${contextBlock}
+## Instructions
+
+- Use FULL mode for all fields \u2014 you are writing new content.
+
+${buildOutputFormatBlock(fields)}`;
+    return {
+      systemPrompt,
+      userMessage: params.instruction
+    };
+  }
+});

package/dist/modules/agent/runtime/server/templates/definitions/rewrite.d.ts

@@ -0,0 +1,5 @@
+type RewriteParams = {
+    instruction: string;
+};
+declare const _default: import("..").StreamTemplateDefinition<RewriteParams>;
+export default _default;

package/dist/modules/agent/runtime/server/templates/definitions/rewrite.js

@@ -0,0 +1,14 @@
+import { defineStreamTemplate } from "../defineStreamTemplate.js";
+import { buildOutputFormatBlock } from "../utils.js";
+export default defineStreamTemplate({
+  name: "rewrite",
+  build: (params, fields) => {
+    const systemPrompt = `You are a text editing assistant. Your task is to write or transform text fields according to the user's instruction.
+
+${buildOutputFormatBlock(fields)}`;
+    return {
+      systemPrompt,
+      userMessage: params.instruction
+    };
+  }
+});

package/dist/modules/agent/runtime/server/templates/definitions/translate.d.ts

@@ -0,0 +1,5 @@
+type TranslateParams = {
+    targetLanguage: string;
+};
+declare const _default: import("..").StreamTemplateDefinition<TranslateParams>;
+export default _default;

package/dist/modules/agent/runtime/server/templates/definitions/translate.js

@@ -0,0 +1,23 @@
+import { defineStreamTemplate } from "../defineStreamTemplate.js";
+import { buildOutputFormatBlock } from "../utils.js";
+export default defineStreamTemplate({
+  name: "translate",
+  defaultInstructions: `- Preserve the original tone, style, and level of formality.
+- Do NOT transliterate proper nouns unless there is a well-known translation.`,
+  build: (params, fields) => {
+    const systemPrompt = `You are a professional translator. Your task is to translate text fields into ${params.targetLanguage}.
+
+## Instructions
+
+- Translate ALL fields completely into ${params.targetLanguage}.
+- Use FULL mode for every field \u2014 translations always require complete replacement.
+- For HTML fields: preserve all HTML tags and structure exactly. Only translate the text content.
+- Do NOT add, remove, or restructure HTML elements.
+
+${buildOutputFormatBlock(fields)}`;
+    return {
+      systemPrompt,
+      userMessage: `Translate all fields into ${params.targetLanguage}.`
+    };
+  }
+});

package/dist/modules/agent/runtime/server/templates/index.d.ts

@@ -0,0 +1,37 @@
+import type { FieldInput } from './types.js';
+import fixReadability from './definitions/fixReadability.js';
+import translate from './definitions/translate.js';
+import rewrite from './definitions/rewrite.js';
+import generateContent from './definitions/generateContent.js';
+export { defineStreamTemplate } from './defineStreamTemplate.js';
+export { buildOutputFormatBlock } from './utils.js';
+export type { FieldInput, TemplateResult, StreamTemplateDefinition, } from './types.js';
+type FixReadabilityParams = Parameters<(typeof fixReadability)['build']>[0];
+type TranslateParams = Parameters<(typeof translate)['build']>[0];
+type RewriteParams = Parameters<(typeof rewrite)['build']>[0];
+type GenerateContentParams = Parameters<(typeof generateContent)['build']>[0];
+export type TemplateCall = {
+    template: 'fix_readability';
+    templateParams: FixReadabilityParams;
+} | {
+    template: 'translate';
+    templateParams: TranslateParams;
+} | {
+    template: 'rewrite';
+    templateParams: RewriteParams;
+} | {
+    template: 'generate_content';
+    templateParams: GenerateContentParams;
+};
+/**
+ * Resolve a template call into a system prompt and user message
+ * for the streaming sub-agent. Optionally includes additional context
+ * from skills that provide stream context for the given template.
+ *
+ * When skill context is provided, it replaces the template's
+ * defaultInstructions. They are never both appended.
+ */
+export declare function resolveTemplate(call: TemplateCall, fields: FieldInput[], skillContext?: string): {
+    systemPrompt: string;
+    userMessage: string;
+};

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

@@ -0,0 +1,25 @@
+import fixReadability from "./definitions/fixReadability.js";
+import translate from "./definitions/translate.js";
+import rewrite from "./definitions/rewrite.js";
+import generateContent from "./definitions/generateContent.js";
+export { defineStreamTemplate } from "./defineStreamTemplate.js";
+export { buildOutputFormatBlock } from "./utils.js";
+const templates = [
+  fixReadability,
+  translate,
+  rewrite,
+  generateContent
+];
+export function resolveTemplate(call, fields, skillContext) {
+  const template = templates.find((t) => t.name === call.template);
+  if (!template) {
+    throw new Error(`Unknown stream template: ${call.template}`);
+  }
+  const result = template.build(call.templateParams, fields);
+  if (skillContext) {
+    result.systemPrompt += "\n\n" + skillContext;
+  } else if (template.defaultInstructions) {
+    result.systemPrompt += "\n\n" + template.defaultInstructions;
+  }
+  return result;
+}

package/dist/modules/agent/runtime/server/templates/types.d.ts

@@ -0,0 +1,17 @@
+import type { StreamTemplateName } from '../skills/types.js';
+export type FieldInput = {
+    uuid: string;
+    fieldName: string;
+    currentValue: string;
+    fieldType: 'plain' | 'markup';
+};
+export type TemplateResult = {
+    systemPrompt: string;
+    userMessage: string;
+};
+export type StreamTemplateDefinition<TParams = unknown> = {
+    name: StreamTemplateName;
+    build: (params: TParams, fields: FieldInput[]) => TemplateResult;
+    /** Appended to system prompt only when no skill provides context. */
+    defaultInstructions?: string;
+};

package/dist/modules/agent/runtime/server/templates/utils.d.ts

@@ -0,0 +1,5 @@
+import type { FieldInput } from './types.js';
+/**
+ * Build the output format docs and field listings shared by all templates.
+ */
+export declare function buildOutputFormatBlock(fields: FieldInput[]): string;

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

@@ -0,0 +1,69 @@
+export function buildOutputFormatBlock(fields) {
+  const fieldDescriptions = fields.map((f, i) => {
+    const typeLabel = f.fieldType === "plain" ? "plain text" : "HTML";
+    const hasContent = f.currentValue.trim().length > 0;
+    if (hasContent) {
+      return `${i}. Type: ${typeLabel}
+   Current value:
+   ${f.currentValue}`;
+    }
+    return `${i}. Type: ${typeLabel}
+   (empty \u2014 write new content)`;
+  }).join("\n\n");
+  return `## Output Format
+
+Use a search-and-replace format to output only the changed portions. There are two modes:
+
+Search/Replace mode \u2014 for targeted edits (typo fixes, small rewrites):
+
+[[[FIELD:0]]]
+[[[SEARCH]]]
+misspelled word
+[[[REPLACE]]]
+correctly spelled word
+
+Multiple search/replace pairs per field are allowed:
+
+[[[FIELD:0]]]
+[[[SEARCH]]]
+first error
+[[[REPLACE]]]
+first fix
+[[[SEARCH]]]
+second error
+[[[REPLACE]]]
+second fix
+
+Full mode \u2014 for translations, complete rewrites, or empty fields:
+
+[[[FIELD:2]]]
+[[[FULL]]]
+The complete new value for this field...
+
+Mixed example (search/replace in one field, full replacement in another):
+
+[[[FIELD:0]]]
+[[[SEARCH]]]
+mispelled
+[[[REPLACE]]]
+misspelled
+[[[FIELD:3]]]
+[[[FULL]]]
+Der \xFCbersetzte Text...
+
+## Rules
+
+- Use [[[FIELD:N]]] to start edits for the field at 0-based index N.
+- Only include fields that need changes. Omit unchanged fields entirely.
+- Choose the mode per field:
+  - Use [[[SEARCH]]] / [[[REPLACE]]] for targeted edits (typo fixes, small changes). Keep the search text minimal \u2014 just the word or phrase being changed. Only add surrounding context if the search text appears multiple times in the field and needs disambiguation.
+  - Use [[[FULL]]] for translations, complete rewrites, or when writing content for empty fields.
+- For "plain text" fields: output plain text only, NO HTML tags.
+- For "HTML" fields: output valid HTML. Preserve the HTML structure (tags like <p>, <ul>, <li>, <h2>, etc.). Do NOT add wrapper elements that weren't there before.
+- Do NOT output anything before the first [[[FIELD:N]]] marker or after the last field's content.
+- Do NOT add any commentary, explanations, or markdown formatting. Output ONLY the raw markers and field content, nothing else.
+
+## Fields
+
+${fieldDescriptions}`;
+}

package/dist/modules/agent/runtime/shared/placeholders.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Replaced with the name of the current user.
+ */
+export declare const PLACEHOLDER_USER_NAME = "@BKUSERNAME";

package/dist/modules/agent/runtime/shared/placeholders.js

@@ -0,0 +1 @@
+export const PLACEHOLDER_USER_NAME = "@BKUSERNAME";

package/dist/modules/agent/runtime/shared/toolParams.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+/**
+ * A boolean parameter that also accepts the strings `"true"` / `"false"` (any
+ * case), coercing them to real booleans. LLMs frequently send a stringified
+ * boolean (e.g. `requireApproval: "false"`) and would otherwise fail validation
+ * on the first call. The generated JSON Schema still advertises a boolean, so
+ * the model is guided toward the real type while the string form is accepted as
+ * a fallback. Mirrors `stringArrayParam` / `z.coerce.number()` used elsewhere.
+ *
+ * Type-aware on purpose: it only fires where a boolean is expected, so a string
+ * param that happens to equal `"false"` is never clobbered. Genuinely invalid
+ * values (e.g. `"maybe"`) still fail validation rather than being swallowed.
+ *
+ * Lives in `shared/` so both client tools and server-only tools build the same
+ * coercion into their respective bundles from one source.
+ *
+ * Return type is explicit so mkdist's isolated-declaration emit preserves it
+ * when this helper appears nested inside another schema. Chaining `.optional()`
+ * or `.default()` on the result would degrade to `any` in the published `.d.ts`
+ * — use {@link optionalBooleanParam} / {@link booleanParamWithDefault} instead.
+ */
+export declare function booleanParam(description: string): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;
+/**
+ * Optional variant of {@link booleanParam}. Use instead of
+ * `booleanParam(...).optional()` so isolated-declaration emit can preserve the
+ * type — chained Zod method calls aren't resolvable by mkdist's per-file
+ * declaration emit and collapse to `any` in the published `.d.ts`.
+ */
+export declare function optionalBooleanParam(description: string): z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>;
+/**
+ * Optional boolean with a default. Use instead of
+ * `booleanParam(...).optional().default(value)` so isolated-declaration emit
+ * can preserve the type. The default value applies when the param is omitted
+ * or `undefined` at parse time.
+ */
+export declare function booleanParamWithDefault(description: string, defaultValue: boolean): z.ZodDefault<z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+/**
+ * Coerce double-serialized array/object params back to their real values.
+ *
+ * LLMs sometimes send e.g. `"[\"x\"]"` (a string) instead of `["x"]` (an array).
+ * This walks the params and attempts `JSON.parse` on any string that looks like
+ * a JSON array or object.
+ *
+ * Pure utility shared by the client (tool execution) and the server (tool
+ * validation/dispatch), so both sides coerce identically.
+ */
+export declare function coerceStringifiedParams(params: Record<string, unknown>): Record<string, unknown>;

package/dist/modules/agent/runtime/shared/toolParams.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+export function booleanParam(description) {
+  return z.preprocess((value) => {
+    if (typeof value === "string") {
+      const lower = value.trim().toLowerCase();
+      if (lower === "true") return true;
+      if (lower === "false") return false;
+    }
+    return value;
+  }, z.boolean().describe(description));
+}
+export function optionalBooleanParam(description) {
+  return booleanParam(description).optional();
+}
+export function booleanParamWithDefault(description, defaultValue) {
+  return booleanParam(description).optional().default(defaultValue);
+}
+export function coerceStringifiedParams(params) {
+  const result = {};
+  for (const key of Object.keys(params)) {
+    const value = params[key];
+    if (typeof value === "string" && (value[0] === "[" || value[0] === "{")) {
+      try {
+        result[key] = JSON.parse(value);
+      } catch {
+        result[key] = value;
+      }
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/dist/modules/agent/runtime/shared/toolResult.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Typed value object for a single tool result.
+ *
+ * A tool result crosses the wire as an opaque JSON **string** (both LLM provider
+ * APIs require `tool_result.content` to be a string). Historically the pruning
+ * code re-`JSON.parse`d that string and inspected untyped fields
+ * (`parsed._summary`, `.label`, `.success`, ...) to decide how to compress it.
+ * `ToolResult` does that classification ONCE, into a typed {@link ToolResultEnvelope},
+ * and exposes pure, deterministic transforms used by the conversation projection.
+ *
+ * It keeps the original wire string verbatim (`raw`) so an un-compressed result
+ * re-serialises byte-identically (important for Anthropic prompt-cache prefix
+ * matching); compressed/stale forms are tiny fixed-shape objects.
+ *
+ * Pure utility shared by the client-facing protocol and the server projection,
+ * mirroring the `shared/toolParams.ts` precedent. No client-tool Zod schemas are
+ * imported here — classification is field-driven, matching the fact that results
+ * are never validated against their schema server-side.
+ */
+/**
+ * Typed classification of a tool result, derived once from its wire content.
+ * The `summaryText` carried on several variants is the explicit summary the
+ * client/tool provided (`_summary ?? label ?? summary`), which takes precedence
+ * when compressing — preserving the historical compression precedence.
+ */
+export type ToolResultEnvelope = {
+    kind: 'opaque';
+    text: string;
+} | {
+    kind: 'stale';
+    summary: string;
+} | {
+    kind: 'error';
+    message: string;
+    summaryText?: string;
+} | {
+    kind: 'mutationSuccess';
+    summaryText?: string;
+} | {
+    kind: 'mutationRejected';
+    summaryText?: string;
+} | {
+    kind: 'selection';
+    selected: unknown;
+    summaryText?: string;
+} | {
+    kind: 'summary';
+    summary: string;
+};
+export declare class ToolResult {
+    /** The original (or compressed) wire string, emitted verbatim by `toWire`. */
+    private readonly raw;
+    private readonly envelope;
+    private readonly isError;
+    /** Summary used when this result is evicted as stale (`_summary ?? summary`). */
+    private readonly staleSummary;
+    private constructor();
+    /**
+     * Classify a wire string (the form stored in a `tool_result` block) once.
+     * Mirrors the historical `compressToolResult` precedence.
+     */
+    static fromWire(content: string, isError?: boolean): ToolResult;
+    /**
+     * Build from a live client result object (server tool-dispatch path).
+     * Applies the `agentMessage → label` rewrite and serialises with the same
+     * bytes the previous code produced, then classifies.
+     */
+    static fromClientResult(result: unknown, opts?: {
+        isError?: boolean;
+    }): ToolResult;
+    /** An explicit error result (malformed input, loop guard, validation, ...). */
+    static error(message: string): ToolResult;
+    /** The wire string for this result — verbatim original, or the compressed form. */
+    toWire(): string;
+    isErrorResult(): boolean;
+    /** True for an applied mutation (`{ success: true }`), independent of summary. */
+    isMutationSuccess(): boolean;
+    /** Best human-readable summary of this result. */
+    summary(): string;
+    /** Estimated token cost of the full wire content (~4 chars per token). */
+    estimatedTokens(): number;
+    /**
+     * Compressed form: collapse to the minimal payload. Pure (returns a new
+     * `ToolResult`) and idempotent. Replicates the historical `compressToolResult`
+     * precedence: an explicit `summaryText` wins; otherwise the kind-specific
+     * minimal shape (`{error}` / `{success}` / `{selected}`) is kept.
+     */
+    compressed(): ToolResult;
+    /**
+     * Stale form: a volatile query whose data is outdated because a mutation
+     * happened after it. Pure and idempotent.
+     *
+     * Error results are preserved verbatim — a failed call isn't "stale data",
+     * it's a failure the LLM may still need to act on (e.g. fix its input and
+     * retry). Collapsing it to a generic stale summary hides the cause.
+     */
+    stale(): ToolResult;
+}