context-mode 0.9.21 → 1.0.0

package/build/session/snapshot.js

@@ -0,0 +1,309 @@
+/**
+ * Snapshot builder — converts stored SessionEvents into an XML resume snapshot.
+ *
+ * Pure functions only. No database access, no file system, no side effects.
+ * The output XML is injected into Claude's context after a compact event to
+ * restore session awareness.
+ *
+ * Budget: default 2048 bytes, allocated by priority tier:
+ *   P1 (file, task, rule):                          50% = ~1024 bytes
+ *   P2 (cwd, error, decision, env, git):            35% = ~716 bytes
+ *   P3-P4 (subagent, skill, role, data, intent):    15% = ~308 bytes
+ */
+import { escapeXML, truncateString } from "../truncate.js";
+// ── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_BYTES = 2048;
+const MAX_ACTIVE_FILES = 10;
+// Priority tier category groupings
+const P1_CATEGORIES = new Set(["file", "task", "rule"]);
+const P2_CATEGORIES = new Set(["cwd", "error", "decision", "env", "git"]);
+// P3-P4: everything else (subagent, skill, role, data, intent, mcp)
+// ── Section renderers ────────────────────────────────────────────────────────
+/**
+ * Render <active_files> from file events.
+ * Deduplicates by path, counts operations, keeps the last 10 files.
+ */
+export function renderActiveFiles(fileEvents) {
+    if (fileEvents.length === 0)
+        return "";
+    // Build per-file operation counts and track last operation
+    const fileMap = new Map();
+    for (const ev of fileEvents) {
+        const path = ev.data;
+        let entry = fileMap.get(path);
+        if (!entry) {
+            entry = { ops: new Map(), last: "" };
+            fileMap.set(path, entry);
+        }
+        // Derive operation from event type
+        let op;
+        if (ev.type === "file_write")
+            op = "write";
+        else if (ev.type === "file_read")
+            op = "read";
+        else
+            op = "edit"; // type === "file" (from Edit tool)
+        entry.ops.set(op, (entry.ops.get(op) ?? 0) + 1);
+        entry.last = op;
+    }
+    // Limit to last MAX_ACTIVE_FILES files (by insertion order = chronological)
+    const entries = Array.from(fileMap.entries());
+    const limited = entries.slice(-MAX_ACTIVE_FILES);
+    const lines = ["  <active_files>"];
+    for (const [path, { ops, last }] of limited) {
+        const opsStr = Array.from(ops.entries())
+            .map(([k, v]) => `${k}:${v}`)
+            .join(",");
+        lines.push(`    <file path="${escapeXML(path)}" ops="${escapeXML(opsStr)}" last="${escapeXML(last)}" />`);
+    }
+    lines.push("  </active_files>");
+    return lines.join("\n");
+}
+/**
+ * Render <task_state> from task events.
+ * Shows the most recent task state (last event's data).
+ */
+export function renderTaskState(taskEvents) {
+    if (taskEvents.length === 0)
+        return "";
+    // Use the last task event as the most current state
+    const lastTask = taskEvents[taskEvents.length - 1];
+    const data = truncateString(escapeXML(lastTask.data), 200);
+    return `  <task_state>\n    ${data}\n  </task_state>`;
+}
+/**
+ * Render <rules> from rule events.
+ * Lists each unique rule source path + content summaries.
+ */
+export function renderRules(ruleEvents) {
+    if (ruleEvents.length === 0)
+        return "";
+    const seen = new Set();
+    const lines = ["  <rules>"];
+    for (const ev of ruleEvents) {
+        const key = ev.data;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (ev.type === "rule_content") {
+            // Rule content: render as content block (survives compact)
+            lines.push(`    <rule_content>${escapeXML(truncateString(ev.data, 400))}</rule_content>`);
+        }
+        else {
+            // Rule path
+            lines.push(`    - ${escapeXML(truncateString(ev.data, 200))}`);
+        }
+    }
+    lines.push("  </rules>");
+    return lines.join("\n");
+}
+/**
+ * Render <decisions> from decision events.
+ */
+export function renderDecisions(decisionEvents) {
+    if (decisionEvents.length === 0)
+        return "";
+    const seen = new Set();
+    const lines = ["  <decisions>"];
+    for (const ev of decisionEvents) {
+        const key = ev.data;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        lines.push(`    - ${escapeXML(truncateString(ev.data, 200))}`);
+    }
+    lines.push("  </decisions>");
+    return lines.join("\n");
+}
+/**
+ * Render <environment> from cwd, env, and git events.
+ */
+export function renderEnvironment(cwdEvent, envEvents, gitEvent) {
+    const parts = [];
+    if (!cwdEvent && envEvents.length === 0 && !gitEvent)
+        return "";
+    parts.push("  <environment>");
+    if (cwdEvent) {
+        parts.push(`    <cwd>${escapeXML(cwdEvent.data)}</cwd>`);
+    }
+    if (gitEvent) {
+        // git event data is the operation type (branch, commit, push, etc.)
+        parts.push(`    <git op="${escapeXML(gitEvent.data)}" />`);
+    }
+    for (const env of envEvents) {
+        parts.push(`    <env>${escapeXML(truncateString(env.data, 150))}</env>`);
+    }
+    parts.push("  </environment>");
+    return parts.join("\n");
+}
+/**
+ * Render <errors_resolved> from error events.
+ */
+export function renderErrors(errorEvents) {
+    if (errorEvents.length === 0)
+        return "";
+    const lines = ["  <errors_resolved>"];
+    for (const ev of errorEvents) {
+        lines.push(`    - ${escapeXML(truncateString(ev.data, 150))}`);
+    }
+    lines.push("  </errors_resolved>");
+    return lines.join("\n");
+}
+/**
+ * Render <intent> from the most recent intent event.
+ */
+export function renderIntent(intentEvent) {
+    return `  <intent mode="${escapeXML(intentEvent.data)}">${escapeXML(truncateString(intentEvent.data, 100))}</intent>`;
+}
+/**
+ * Render <mcp_tools> from MCP tool call events.
+ * Deduplicates by tool name, shows usage count.
+ */
+export function renderMcpTools(mcpEvents) {
+    if (mcpEvents.length === 0)
+        return "";
+    // Count usage per tool
+    const toolCounts = new Map();
+    for (const ev of mcpEvents) {
+        const tool = ev.data.split(":")[0].trim();
+        toolCounts.set(tool, (toolCounts.get(tool) ?? 0) + 1);
+    }
+    const lines = ["  <mcp_tools>"];
+    for (const [tool, count] of toolCounts) {
+        lines.push(`    <tool name="${escapeXML(tool)}" calls="${count}" />`);
+    }
+    lines.push("  </mcp_tools>");
+    return lines.join("\n");
+}
+// ── Main builder ─────────────────────────────────────────────────────────────
+/**
+ * Build a resume snapshot XML string from stored session events.
+ *
+ * Algorithm:
+ * 1. Group events by category
+ * 2. Render each section
+ * 3. Assemble by priority tier with budget trimming
+ * 4. If over maxBytes, drop lowest priority sections first
+ */
+export function buildResumeSnapshot(events, opts) {
+    const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const compactCount = opts?.compactCount ?? 1;
+    const now = new Date().toISOString();
+    // ── Group events by category ──
+    const fileEvents = [];
+    const taskEvents = [];
+    const ruleEvents = [];
+    const decisionEvents = [];
+    const cwdEvents = [];
+    const errorEvents = [];
+    const envEvents = [];
+    const gitEvents = [];
+    const skillEvents = [];
+    const subagentEvents = [];
+    const roleEvents = [];
+    const dataEvents = [];
+    const intentEvents = [];
+    const mcpEvents = [];
+    for (const ev of events) {
+        switch (ev.category) {
+            case "file":
+                fileEvents.push(ev);
+                break;
+            case "task":
+                taskEvents.push(ev);
+                break;
+            case "rule":
+                ruleEvents.push(ev);
+                break;
+            case "decision":
+                decisionEvents.push(ev);
+                break;
+            case "cwd":
+                cwdEvents.push(ev);
+                break;
+            case "error":
+                errorEvents.push(ev);
+                break;
+            case "env":
+                envEvents.push(ev);
+                break;
+            case "git":
+                gitEvents.push(ev);
+                break;
+            case "skill":
+                skillEvents.push(ev);
+                break;
+            case "subagent":
+                subagentEvents.push(ev);
+                break;
+            case "role":
+                roleEvents.push(ev);
+                break;
+            case "data":
+                dataEvents.push(ev);
+                break;
+            case "intent":
+                intentEvents.push(ev);
+                break;
+            case "mcp":
+                mcpEvents.push(ev);
+                break;
+        }
+    }
+    // ── Render sections by priority tier ──
+    // P1 sections (50% budget): active_files, task_state, rules
+    const p1Sections = [];
+    const activeFiles = renderActiveFiles(fileEvents);
+    if (activeFiles)
+        p1Sections.push(activeFiles);
+    const taskState = renderTaskState(taskEvents);
+    if (taskState)
+        p1Sections.push(taskState);
+    const rules = renderRules(ruleEvents);
+    if (rules)
+        p1Sections.push(rules);
+    // P2 sections (35% budget): decisions, environment, errors_resolved
+    const p2Sections = [];
+    const decisions = renderDecisions(decisionEvents);
+    if (decisions)
+        p2Sections.push(decisions);
+    const lastCwd = cwdEvents.length > 0 ? cwdEvents[cwdEvents.length - 1] : undefined;
+    const lastGit = gitEvents.length > 0 ? gitEvents[gitEvents.length - 1] : undefined;
+    const environment = renderEnvironment(lastCwd, envEvents, lastGit);
+    if (environment)
+        p2Sections.push(environment);
+    const errors = renderErrors(errorEvents);
+    if (errors)
+        p2Sections.push(errors);
+    // P3-P4 sections (15% budget): intent, mcp_tools
+    const p3Sections = [];
+    if (intentEvents.length > 0) {
+        const lastIntent = intentEvents[intentEvents.length - 1];
+        p3Sections.push(renderIntent(lastIntent));
+    }
+    const mcpTools = renderMcpTools(mcpEvents);
+    if (mcpTools)
+        p3Sections.push(mcpTools);
+    // ── Assemble with budget trimming ──
+    const header = `<session_resume compact_count="${compactCount}" events_captured="${events.length}" generated_at="${now}">`;
+    const footer = `</session_resume>`;
+    // Try assembling all tiers, drop lowest priority first if over budget
+    const tiers = [p1Sections, p2Sections, p3Sections];
+    // Start with all tiers and progressively drop from the back
+    for (let dropFrom = tiers.length; dropFrom >= 0; dropFrom--) {
+        const activeTiers = tiers.slice(0, dropFrom);
+        const body = activeTiers.flat().join("\n");
+        let xml;
+        if (body) {
+            xml = `${header}\n${body}\n${footer}`;
+        }
+        else {
+            xml = `${header}\n${footer}`;
+        }
+        if (Buffer.byteLength(xml) <= maxBytes) {
+            return xml;
+        }
+    }
+    // If even header+footer is over budget, return the minimal XML
+    return `${header}\n${footer}`;
+}

package/build/store.d.ts

@@ -7,26 +7,8 @@
  * Use for documentation, API references, and any content where
  * you need EXACT text later — not summaries.
  */
-export interface IndexResult {
-    sourceId: number;
-    label: string;
-    totalChunks: number;
-    codeChunks: number;
-}
-export interface SearchResult {
-    title: string;
-    content: string;
-    source: string;
-    rank: number;
-    contentType: "code" | "prose";
-    matchLayer?: "porter" | "trigram" | "fuzzy";
-    highlighted?: string;
-}
-export interface StoreStats {
-    sources: number;
-    chunks: number;
-    codeChunks: number;
-}
+import type { IndexResult, SearchResult, StoreStats } from "./types.js";
+export type { IndexResult, SearchResult, StoreStats } from "./types.js";
 /**
  * Remove stale DB files from previous sessions whose processes no longer exist.
  */
@@ -55,8 +37,8 @@ export declare class ContentStore {
      * Falls back to `indexPlainText` if the content is not valid JSON.
      */
     indexJSON(content: string, source: string, maxChunkBytes?: number): IndexResult;
-    search(query: string, limit?: number, source?: string): SearchResult[];
-    searchTrigram(query: string, limit?: number, source?: string): SearchResult[];
+    search(query: string, limit?: number, source?: string, mode?: "AND" | "OR"): SearchResult[];
+    searchTrigram(query: string, limit?: number, source?: string, mode?: "AND" | "OR"): SearchResult[];
     fuzzyCorrect(query: string): string | null;
     searchWithFallback(query: string, limit?: number, source?: string): SearchResult[];
     listSources(): Array<{

package/build/store.js

@@ -7,21 +7,10 @@
  * Use for documentation, API references, and any content where
  * you need EXACT text later — not summaries.
  */
-import { createRequire } from "node:module";
+import { loadDatabase, applyWALPragmas } from "./db-base.js";
 import { readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-// Lazy-load better-sqlite3 — only when ContentStore is first used.
-// This lets the MCP server start instantly even if the native module
-// isn't installed yet (marketplace first-run scenario).
-let _Database = null;
-function loadDatabase() {
-    if (!_Database) {
-        const require = createRequire(import.meta.url);
-        _Database = require("better-sqlite3");
-    }
-    return _Database;
-}
 // ─────────────────────────────────────────────────────────
 // Constants
 // ─────────────────────────────────────────────────────────
@@ -43,7 +32,7 @@ const STOPWORDS = new Set([
 // ─────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────
-function sanitizeQuery(query) {
+function sanitizeQuery(query, mode = "AND") {
     const words = query
         .replace(/['"(){}[\]*:^~]/g, " ")
         .split(/\s+/)
@@ -51,16 +40,16 @@ function sanitizeQuery(query) {
         !["AND", "OR", "NOT", "NEAR"].includes(w.toUpperCase()));
     if (words.length === 0)
         return '""';
-    return words.map((w) => `"${w}"`).join(" OR ");
+    return words.map((w) => `"${w}"`).join(mode === "OR" ? " OR " : " ");
 }
-function sanitizeTrigramQuery(query) {
+function sanitizeTrigramQuery(query, mode = "AND") {
     const cleaned = query.replace(/["'(){}[\]*:^~]/g, "").trim();
     if (cleaned.length < 3)
         return "";
     const words = cleaned.split(/\s+/).filter((w) => w.length >= 3);
     if (words.length === 0)
         return "";
-    return words.map((w) => `"${w}"`).join(" OR ");
+    return words.map((w) => `"${w}"`).join(mode === "OR" ? " OR " : " ");
 }
 function levenshtein(a, b) {
     if (a.length === 0)
@@ -139,6 +128,10 @@ export class ContentStore {
     #stmtInsertChunk;
     #stmtInsertChunkTrigram;
     #stmtInsertVocab;
+    // Dedup path (delete previous source with same label before re-indexing)
+    #stmtDeleteChunksByLabel;
+    #stmtDeleteChunksTrigramByLabel;
+    #stmtDeleteSourcesByLabel;
     // Search path (hot)
     #stmtSearchPorter;
     #stmtSearchPorterFiltered;
@@ -156,8 +149,7 @@ export class ContentStore {
         this.#dbPath =
             dbPath ?? join(tmpdir(), `context-mode-${process.pid}.db`);
         this.#db = new Database(this.#dbPath, { timeout: 5000 });
-        this.#db.pragma("journal_mode = WAL");
-        this.#db.pragma("synchronous = NORMAL");
+        applyWALPragmas(this.#db);
         this.#initSchema();
         this.#prepareStatements();
     }
@@ -213,6 +205,11 @@ export class ContentStore {
         this.#stmtInsertChunk = this.#db.prepare("INSERT INTO chunks (title, content, source_id, content_type) VALUES (?, ?, ?, ?)");
         this.#stmtInsertChunkTrigram = this.#db.prepare("INSERT INTO chunks_trigram (title, content, source_id, content_type) VALUES (?, ?, ?, ?)");
         this.#stmtInsertVocab = this.#db.prepare("INSERT OR IGNORE INTO vocabulary (word) VALUES (?)");
+        // Dedup path: delete previous source with same label before re-indexing
+        // Prevents stale outputs from accumulating in iterative workflows (build-fix-build)
+        this.#stmtDeleteChunksByLabel = this.#db.prepare("DELETE FROM chunks WHERE source_id IN (SELECT id FROM sources WHERE label = ?)");
+        this.#stmtDeleteChunksTrigramByLabel = this.#db.prepare("DELETE FROM chunks_trigram WHERE source_id IN (SELECT id FROM sources WHERE label = ?)");
+        this.#stmtDeleteSourcesByLabel = this.#db.prepare("DELETE FROM sources WHERE label = ?");
         // Search path (hot)
         this.#stmtSearchPorter = this.#db.prepare(`
       SELECT
@@ -345,17 +342,18 @@ export class ContentStore {
      * Uses cached prepared statements from #prepareStatements().
      */
     #insertChunks(chunks, label, text) {
-        if (chunks.length === 0) {
-            const info = this.#stmtInsertSourceEmpty.run(label);
-            return {
-                sourceId: Number(info.lastInsertRowid),
-                label,
-                totalChunks: 0,
-                codeChunks: 0,
-            };
-        }
         const codeChunks = chunks.filter((c) => c.hasCode).length;
+        // Atomic dedup + insert: delete previous source with same label,
+        // then insert new content — all within a single transaction.
+        // Prevents stale results in iterative workflows. (See: GitHub issue #67)
         const transaction = this.#db.transaction(() => {
+            this.#stmtDeleteChunksByLabel.run(label);
+            this.#stmtDeleteChunksTrigramByLabel.run(label);
+            this.#stmtDeleteSourcesByLabel.run(label);
+            if (chunks.length === 0) {
+                const info = this.#stmtInsertSourceEmpty.run(label);
+                return Number(info.lastInsertRowid);
+            }
             const info = this.#stmtInsertSource.run(label, chunks.length, codeChunks);
             const sourceId = Number(info.lastInsertRowid);
             for (const chunk of chunks) {
@@ -366,7 +364,8 @@ export class ContentStore {
             return sourceId;
         });
         const sourceId = transaction();
-        this.#extractAndStoreVocabulary(text);
+        if (text)
+            this.#extractAndStoreVocabulary(text);
         return {
             sourceId,
             label,
@@ -375,8 +374,8 @@ export class ContentStore {
         };
     }
     // ── Search ──
-    search(query, limit = 3, source) {
-        const sanitized = sanitizeQuery(query);
+    search(query, limit = 3, source, mode = "AND") {
+        const sanitized = sanitizeQuery(query, mode);
         const stmt = source
             ? this.#stmtSearchPorterFiltered
             : this.#stmtSearchPorter;
@@ -394,8 +393,8 @@ export class ContentStore {
         }));
     }
     // ── Trigram Search (Layer 2) ──
-    searchTrigram(query, limit = 3, source) {
-        const sanitized = sanitizeTrigramQuery(query);
+    searchTrigram(query, limit = 3, source, mode = "AND") {
+        const sanitized = sanitizeTrigramQuery(query, mode);
         if (!sanitized)
             return [];
         const stmt = source
@@ -436,20 +435,33 @@ export class ContentStore {
     }
     // ── Unified Fallback Search ──
     searchWithFallback(query, limit = 3, source) {
-        // Layer 1: Porter stemming (existing FTS5 MATCH)
-        const porterResults = this.search(query, limit, source);
-        if (porterResults.length > 0) {
-            return porterResults.map((r) => ({ ...r, matchLayer: "porter" }));
+        // Layer 1a: Porter + AND (most precise)
+        const porterAnd = this.search(query, limit, source, "AND");
+        if (porterAnd.length > 0) {
+            return porterAnd.map((r) => ({ ...r, matchLayer: "porter" }));
+        }
+        // Layer 1b: Porter + OR (fallback when AND finds nothing)
+        const porterOr = this.search(query, limit, source, "OR");
+        if (porterOr.length > 0) {
+            return porterOr.map((r) => ({ ...r, matchLayer: "porter" }));
         }
-        // Layer 2: Trigram substring matching
-        const trigramResults = this.searchTrigram(query, limit, source);
-        if (trigramResults.length > 0) {
-            return trigramResults.map((r) => ({
+        // Layer 2a: Trigram + AND
+        const trigramAnd = this.searchTrigram(query, limit, source, "AND");
+        if (trigramAnd.length > 0) {
+            return trigramAnd.map((r) => ({
                 ...r,
                 matchLayer: "trigram",
             }));
         }
-        // Layer 3: Fuzzy correction + re-search
+        // Layer 2b: Trigram + OR
+        const trigramOr = this.searchTrigram(query, limit, source, "OR");
+        if (trigramOr.length > 0) {
+            return trigramOr.map((r) => ({
+                ...r,
+                matchLayer: "trigram",
+            }));
+        }
+        // Layer 3: Fuzzy correction + re-search (AND then OR)
         const words = query
             .toLowerCase()
             .trim()
@@ -459,21 +471,21 @@ export class ContentStore {
         const correctedWords = words.map((w) => this.fuzzyCorrect(w) ?? w);
         const correctedQuery = correctedWords.join(" ");
         if (correctedQuery !== original) {
-            // Try Porter with corrected query first
-            const fuzzyPorter = this.search(correctedQuery, limit, source);
-            if (fuzzyPorter.length > 0) {
-                return fuzzyPorter.map((r) => ({
-                    ...r,
-                    matchLayer: "fuzzy",
-                }));
+            const fuzzyPorterAnd = this.search(correctedQuery, limit, source, "AND");
+            if (fuzzyPorterAnd.length > 0) {
+                return fuzzyPorterAnd.map((r) => ({ ...r, matchLayer: "fuzzy" }));
+            }
+            const fuzzyPorterOr = this.search(correctedQuery, limit, source, "OR");
+            if (fuzzyPorterOr.length > 0) {
+                return fuzzyPorterOr.map((r) => ({ ...r, matchLayer: "fuzzy" }));
+            }
+            const fuzzyTrigramAnd = this.searchTrigram(correctedQuery, limit, source, "AND");
+            if (fuzzyTrigramAnd.length > 0) {
+                return fuzzyTrigramAnd.map((r) => ({ ...r, matchLayer: "fuzzy" }));
             }
-            // Try trigram with corrected query
-            const fuzzyTrigram = this.searchTrigram(correctedQuery, limit, source);
-            if (fuzzyTrigram.length > 0) {
-                return fuzzyTrigram.map((r) => ({
-                    ...r,
-                    matchLayer: "fuzzy",
-                }));
+            const fuzzyTrigramOr = this.searchTrigram(correctedQuery, limit, source, "OR");
+            if (fuzzyTrigramOr.length > 0) {
+                return fuzzyTrigramOr.map((r) => ({ ...r, matchLayer: "fuzzy" }));
             }
         }
         return [];

package/build/truncate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * truncate — Pure string and output truncation utilities for context-mode.
+ *
+ * These helpers are used by both the core ContentStore (chunking) and the
+ * PolyglotExecutor (smart output truncation). They are extracted here so
+ * SessionDB and any other future consumer can import them without pulling
+ * in the full store or executor.
+ */
+/**
+ * Truncate a string to at most `maxChars` characters, appending an ellipsis
+ * when truncation occurs.
+ *
+ * @param str     - Input string.
+ * @param maxChars - Maximum character count (inclusive). Must be >= 3.
+ * @returns The original string if short enough, otherwise a truncated string
+ *          ending with "...".
+ */
+export declare function truncateString(str: string, maxChars: number): string;
+/**
+ * Smart truncation that keeps the head (60%) and tail (40%) of output,
+ * preserving both initial context and final error messages.
+ * Snaps to line boundaries and handles UTF-8 safely via `Buffer.byteLength`.
+ *
+ * Used by PolyglotExecutor to cap stdout/stderr before returning to context.
+ *
+ * @param raw - Raw output string.
+ * @param maxBytes - Soft cap in bytes. Output below this threshold is returned as-is.
+ * @returns The original string if within budget, otherwise head + separator + tail.
+ */
+export declare function smartTruncate(raw: string, maxBytes: number): string;
+/**
+ * Serialize a value to JSON, then truncate the result to `maxBytes` bytes.
+ * If truncation occurs, the string is cut at a UTF-8-safe boundary and
+ * "... [truncated]" is appended. The result is NOT guaranteed to be valid
+ * JSON after truncation — it is suitable only for display/logging.
+ *
+ * @param value    - Any JSON-serializable value.
+ * @param maxBytes - Maximum byte length of the returned string.
+ * @param indent   - JSON indentation spaces (default 2). Pass 0 for compact.
+ */
+export declare function truncateJSON(value: unknown, maxBytes: number, indent?: number): string;
+/**
+ * Escape a string for safe embedding in an XML or HTML attribute or text node.
+ * Replaces the five XML-reserved characters: `&`, `<`, `>`, `"`, `'`.
+ *
+ * Used by the resume snapshot template builder to embed user content in
+ * `<tool_response>` and `<user_message>` XML tags without breaking the
+ * structured prompt format.
+ */
+export declare function escapeXML(str: string): string;
+/**
+ * Return `str` unchanged if it fits within `maxBytes`, otherwise return a
+ * byte-safe slice with an ellipsis appended. Useful for single-value fields
+ * (e.g., tool response strings) where head+tail splitting is not needed.
+ *
+ * @param str      - Input string.
+ * @param maxBytes - Hard byte cap.
+ */
+export declare function capBytes(str: string, maxBytes: number): string;