@elizaos/agent 2.0.0-alpha.98 → 2.0.0-beta.2

package/packages/agent/src/runtime/conversation-compactor-runtime.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Runtime integration for conversation-compactor strategies.
+ *
+ * The compactors in conversation-compactor.ts operate on structured
+ * CompactorTranscript objects (role-tagged messages). The Eliza runtime
+ * pipeline at this layer only sees a flat prompt string assembled by the
+ * core providers (`# Conversation Messages` block + system prefix
+ * + `# Received Message` suffix).
+ *
+ * This module bridges the two by:
+ *   1. Best-effort parsing the prompt string into a CompactorTranscript
+ *      (Shape A in the integration design — string-level).
+ *   2. Invoking the chosen Compactor strategy.
+ *   3. Serializing the compacted transcript back into the prompt, replacing
+ *      only the `# Conversation Messages` region and preserving the prefix
+ *      and suffix verbatim.
+ *
+ * Opt-in via `ELIZA_CONVERSATION_COMPACTOR=<strategy>`. When unset, no
+ * conversation-level compaction runs and the existing presentation-layer
+ * compaction + tail truncation pipeline in prompt-optimization.ts is the
+ * only path.
+ *
+ * TODO(message-level): the cleanest integration is a message-level hook
+ * upstream in @elizaos/core that hands the compactor a real transcript
+ * before string assembly. Until that exists, the parse/serialize step
+ * here is best-effort and intentionally conservative.
+ */
+import type { AgentRuntime } from "@elizaos/core";
+import { type CompactionStats, type CompactorMessage, type CompactorModelCall, type CompactorTranscript } from "./conversation-compactor.types.ts";
+export declare const STRATEGY_NAMES: readonly ["naive-summary", "structured-state", "hierarchical-summary", "hybrid-ledger"];
+export type StrategyName = (typeof STRATEGY_NAMES)[number];
+/**
+ * Reads `ELIZA_CONVERSATION_COMPACTOR` from the environment.
+ * Returns `null` when unset (compaction is opt-in).
+ * Throws when set to a value that is not a known strategy name.
+ */
+export declare function selectStrategyFromEnv(): StrategyName | null;
+/**
+ * Best-effort split of an Eliza-assembled prompt into a CompactorTranscript.
+ *
+ * Strategy:
+ *   - Everything before `# Conversation Messages` becomes a single
+ *     system-role message (so the compactor preserves it verbatim — system
+ *     prefix is index 0 and is never summarized).
+ *   - Each turn inside the conversation block becomes one CompactorMessage,
+ *     role = "assistant" if the block has an internal-thought / actions
+ *     annotation (those only appear on agent turns) else "user".
+ *   - Everything from `# Received Message` to end-of-prompt is appended as
+ *     a final user message (so the active turn stays in the preserved tail).
+ *
+ * Failure modes:
+ *   - If `# Conversation Messages` is absent, returns a single user-message
+ *     transcript containing the whole prompt. Downstream compaction will
+ *     then no-op safely (no region to summarize).
+ */
+export declare function parsePromptToTranscript(prompt: string): CompactorTranscript;
+/**
+ * Replaces the `# Conversation Messages` region in `original` with a
+ * compacted version derived from `compacted`. Preserves the prefix and
+ * suffix (`# Received Message`...) verbatim.
+ *
+ * Messages whose `content` matches the original raw block format
+ * (i.e. preserved-tail entries we passed through unchanged) are emitted
+ * exactly as they appeared. Synthesized replacement messages are
+ * rendered with `renderCompactedMessage` to keep them visually distinct.
+ *
+ * If `original` does not contain a `# Conversation Messages` section,
+ * the original prompt is returned unchanged.
+ */
+export declare function serializeTranscriptToPrompt(original: string, compacted: CompactorTranscript): string;
+export type ApplyConversationCompactionArgs = {
+    prompt: string;
+    strategy: StrategyName;
+    /** Current prompt token count (already estimated by the caller). */
+    currentTokens: number;
+    /** Token budget the prompt must fit into. */
+    targetTokens: number;
+    /** Wraps `runtime.useModel(TEXT_LARGE, ...)`; required for summarizers. */
+    callModel: CompactorModelCall;
+    /** Optional — used only for telemetry / logger hookup. */
+    runtime?: AgentRuntime;
+    /** Optional — message-count to preserve verbatim at the tail. */
+    preserveTailMessages?: number;
+};
+export type ApplyConversationCompactionResult = {
+    prompt: string;
+    didCompact: boolean;
+    originalTokens: number;
+    compactedTokens: number;
+    latencyMs: number;
+    strategy: StrategyName | null;
+    targetTokens: number;
+    replacementTargetTokens: number;
+    artifact?: {
+        replacementMessageCount: number;
+        stats: CompactionArtifactStats;
+    };
+};
+export type ApplyConversationMessageCompactionArgs = {
+    messages: CompactorMessage[];
+    strategy: StrategyName;
+    /** Current message token count (already estimated by caller when known). */
+    currentTokens: number;
+    /** Token budget the message list must fit into. */
+    targetTokens: number;
+    /** Wraps `runtime.useModel(TEXT_LARGE, ...)`; required for summarizers. */
+    callModel: CompactorModelCall;
+    /** Optional — message-count to preserve verbatim at the tail. */
+    preserveTailMessages?: number;
+};
+export type ApplyConversationMessageCompactionResult = Omit<ApplyConversationCompactionResult, "prompt"> & {
+    messages: CompactorMessage[];
+};
+type CompactionArtifactStats = {
+    originalMessageCount: CompactionStats["originalMessageCount"];
+    compactedMessageCount: CompactionStats["compactedMessageCount"];
+    originalTokens: CompactionStats["originalTokens"];
+    compactedTokens: CompactionStats["compactedTokens"];
+    summarizationModel?: CompactionStats["summarizationModel"];
+    latencyMs: CompactionStats["latencyMs"];
+    extra?: CompactionStats["extra"];
+};
+/**
+ * Main entry point for runtime conversation-level compaction.
+ *
+ * No-ops when `currentTokens <= targetTokens`. Otherwise parses the prompt,
+ * runs the selected strategy, serializes back, and returns the result.
+ * Always returns; never throws on a parse-failure path (falls back to
+ * the original prompt with `didCompact: false`).
+ */
+export declare function applyConversationCompaction(args: ApplyConversationCompactionArgs): Promise<ApplyConversationCompactionResult>;
+/**
+ * Message-level companion to `applyConversationCompaction`.
+ *
+ * v5 runtime model calls often pass OpenAI-style `messages` directly instead
+ * of a flattened prompt string. This path avoids lossy prompt parsing and
+ * lets the conversation compactor operate on the role-tagged transcript.
+ */
+export declare function applyConversationMessageCompaction(args: ApplyConversationMessageCompactionArgs): Promise<ApplyConversationMessageCompactionResult>;
+export {};
+//# sourceMappingURL=conversation-compactor-runtime.d.ts.map

package/packages/agent/src/runtime/conversation-compactor-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-compactor-runtime.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/conversation-compactor-runtime.ts"],"names":[],"mappings":"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"}

package/packages/agent/src/runtime/conversation-compactor-runtime.js

@@ -0,0 +1,460 @@
+/**
+ * Runtime integration for conversation-compactor strategies.
+ *
+ * The compactors in conversation-compactor.ts operate on structured
+ * CompactorTranscript objects (role-tagged messages). The Eliza runtime
+ * pipeline at this layer only sees a flat prompt string assembled by the
+ * core providers (`# Conversation Messages` block + system prefix
+ * + `# Received Message` suffix).
+ *
+ * This module bridges the two by:
+ *   1. Best-effort parsing the prompt string into a CompactorTranscript
+ *      (Shape A in the integration design — string-level).
+ *   2. Invoking the chosen Compactor strategy.
+ *   3. Serializing the compacted transcript back into the prompt, replacing
+ *      only the `# Conversation Messages` region and preserving the prefix
+ *      and suffix verbatim.
+ *
+ * Opt-in via `ELIZA_CONVERSATION_COMPACTOR=<strategy>`. When unset, no
+ * conversation-level compaction runs and the existing presentation-layer
+ * compaction + tail truncation pipeline in prompt-optimization.ts is the
+ * only path.
+ *
+ * TODO(message-level): the cleanest integration is a message-level hook
+ * upstream in @elizaos/core that hands the compactor a real transcript
+ * before string assembly. Until that exists, the parse/serialize step
+ * here is best-effort and intentionally conservative.
+ */
+import { compactors, findSafeCompactionBoundary, naiveSummaryCompactor, } from "./conversation-compactor.js";
+import { approxCountTokens, countTranscriptTokens, } from "./conversation-compactor.types.js";
+export const STRATEGY_NAMES = [
+    "naive-summary",
+    "structured-state",
+    "hierarchical-summary",
+    "hybrid-ledger",
+];
+const CONVERSATION_HEADER = "# Conversation Messages";
+const CONVERSATION_HEADER_RE = /^#{1,3}\s*Conversation Messages\b/gim;
+const RECEIVED_HEADER_RE = /\n#{1,3}\s*Received Message\b/gi;
+// Match any of:
+//   "12:53 (17 minutes ago) [uuid] Eliza: text"  ← canonical Eliza recorder
+//   "12:53 (17 minutes ago) Eliza: text"          ← without uuid
+//   "12:53 Eliza: text"                            ← minimal (dev/tests)
+// All four capture groups (time, relative, uuid, name, text) are returned, but
+// only `time` and the trailing `name: text` are required.
+const CONVERSATION_LINE_RE = /^(\d{1,2}:\d{2})(?:\s*\(([^)]*)\))?(?:\s*\[([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\])?\s*([^:]+?):\s*(.*)$/i;
+const INTERNAL_THOUGHT_RE = /\([^)]*'s internal thought:[^)]*\)/i;
+const ACTIONS_LINE_RE = /\([^)]*'s actions:[^)]*\)/i;
+const USER_SPEAKER_RE = /^(?:user|operator|human|client|customer)$/i;
+const ASSISTANT_SPEAKER_RE = /^(?:eliza|milady|agent|assistant|system|bot|ai)(?:\s*\([^)]*\))?$/i;
+// ---------------------------------------------------------------------------
+// Env config
+// ---------------------------------------------------------------------------
+/**
+ * Reads `ELIZA_CONVERSATION_COMPACTOR` from the environment.
+ * Returns `null` when unset (compaction is opt-in).
+ * Throws when set to a value that is not a known strategy name.
+ */
+export function selectStrategyFromEnv() {
+    const raw = process.env.ELIZA_CONVERSATION_COMPACTOR;
+    if (raw === undefined || raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    if (STRATEGY_NAMES.includes(trimmed)) {
+        return trimmed;
+    }
+    throw new Error(`ELIZA_CONVERSATION_COMPACTOR=${trimmed} is invalid. ` +
+        `Expected one of: ${STRATEGY_NAMES.join(", ")}`);
+}
+function locateConversationRegion(prompt) {
+    const receivedMatches = [...prompt.matchAll(RECEIVED_HEADER_RE)];
+    const lastReceived = receivedMatches.at(-1);
+    const receivedStart = lastReceived && typeof lastReceived.index === "number"
+        ? lastReceived.index
+        : prompt.length;
+    const conversationMatches = [...prompt.matchAll(CONVERSATION_HEADER_RE)];
+    const startMatch = conversationMatches
+        .filter((match) => typeof match.index === "number" && match.index < receivedStart)
+        .at(-1);
+    if (!startMatch || typeof startMatch.index !== "number")
+        return null;
+    const start = startMatch.index;
+    const endOffset = receivedStart > start ? receivedStart : prompt.length;
+    return {
+        prefix: prompt.slice(0, start),
+        region: prompt.slice(start, endOffset),
+        suffix: prompt.slice(endOffset),
+    };
+}
+function parseConversationBody(body) {
+    const lines = body.split("\n");
+    const blocks = [];
+    let current = null;
+    for (const line of lines) {
+        const match = line.trim().match(CONVERSATION_LINE_RE);
+        const speaker = match?.[4]?.trim() ?? "";
+        const canonicalTurn = Boolean(match?.[2] || match?.[3]);
+        const knownSpeaker = USER_SPEAKER_RE.test(speaker) || ASSISTANT_SPEAKER_RE.test(speaker);
+        if (match && (current === null || canonicalTurn || knownSpeaker)) {
+            if (current)
+                blocks.push(current);
+            current = [line];
+        }
+        else if (current) {
+            current.push(line);
+        }
+        // Lines before any header line are dropped — they belong to the section
+        // header itself, not to any message.
+    }
+    if (current)
+        blocks.push(current);
+    const messages = [];
+    for (const block of blocks) {
+        const headerLine = block[0].trim();
+        const match = headerLine.match(CONVERSATION_LINE_RE);
+        if (!match)
+            continue;
+        const [, time, , , name, text] = match;
+        const blockText = block.join("\n");
+        const normalizedName = name.trim();
+        const isUserSpeaker = USER_SPEAKER_RE.test(normalizedName);
+        const isAssistantSpeaker = ASSISTANT_SPEAKER_RE.test(normalizedName);
+        const role = !isUserSpeaker &&
+            (isAssistantSpeaker ||
+                INTERNAL_THOUGHT_RE.test(blockText) ||
+                ACTIONS_LINE_RE.test(blockText))
+            ? "assistant"
+            : "user";
+        messages.push({
+            role,
+            raw: blockText,
+            name: normalizedName,
+            text: text.trim(),
+            time,
+        });
+    }
+    return messages;
+}
+/**
+ * Best-effort split of an Eliza-assembled prompt into a CompactorTranscript.
+ *
+ * Strategy:
+ *   - Everything before `# Conversation Messages` becomes a single
+ *     system-role message (so the compactor preserves it verbatim — system
+ *     prefix is index 0 and is never summarized).
+ *   - Each turn inside the conversation block becomes one CompactorMessage,
+ *     role = "assistant" if the block has an internal-thought / actions
+ *     annotation (those only appear on agent turns) else "user".
+ *   - Everything from `# Received Message` to end-of-prompt is appended as
+ *     a final user message (so the active turn stays in the preserved tail).
+ *
+ * Failure modes:
+ *   - If `# Conversation Messages` is absent, returns a single user-message
+ *     transcript containing the whole prompt. Downstream compaction will
+ *     then no-op safely (no region to summarize).
+ */
+export function parsePromptToTranscript(prompt) {
+    const region = locateConversationRegion(prompt);
+    if (!region) {
+        return {
+            messages: [{ role: "user", content: prompt }],
+            metadata: { parseFallback: true },
+        };
+    }
+    // Strip the section header line so the body parser doesn't have to
+    // special-case it.
+    const headerStripped = region.region.replace(/^#{1,3}\s*Conversation Messages\b[^\n]*(?:\n)?/i, "");
+    const parsed = parseConversationBody(headerStripped);
+    const messages = [];
+    if (region.prefix.trim().length > 0) {
+        messages.push({
+            role: "system",
+            content: region.prefix.replace(/\n+$/, ""),
+        });
+    }
+    for (const m of parsed) {
+        messages.push({
+            role: m.role,
+            content: m.raw,
+        });
+    }
+    if (region.suffix.trim().length > 0) {
+        messages.push({
+            role: "user",
+            content: region.suffix.replace(/^\n+/, ""),
+        });
+    }
+    return {
+        messages,
+        metadata: {
+            parseFallback: false,
+            prefixChars: region.prefix.length,
+            regionChars: region.region.length,
+            suffixChars: region.suffix.length,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Serialize: CompactorTranscript -> prompt string
+// ---------------------------------------------------------------------------
+function renderCompactedMessage(m) {
+    // Replacement messages emitted by the compactor do not have the
+    // `HH:MM (...) [uuid] Name: text` header format; render them with a
+    // role-prefixed marker instead. The downstream model sees these as
+    // synthesized summaries and has no risk of confusing them with real
+    // conversation turns.
+    const tag = m.tags && m.tags.length > 0 ? ` [${m.tags.join(",")}]` : "";
+    switch (m.role) {
+        case "system":
+            return `[system summary${tag}] ${m.content}`;
+        case "assistant":
+            return `[Agent${tag}] ${m.content}`;
+        case "tool":
+            return `[Tool${m.toolName ? `:${m.toolName}` : ""}${tag}] ${m.content}`;
+        default:
+            return m.content;
+    }
+}
+/**
+ * Replaces the `# Conversation Messages` region in `original` with a
+ * compacted version derived from `compacted`. Preserves the prefix and
+ * suffix (`# Received Message`...) verbatim.
+ *
+ * Messages whose `content` matches the original raw block format
+ * (i.e. preserved-tail entries we passed through unchanged) are emitted
+ * exactly as they appeared. Synthesized replacement messages are
+ * rendered with `renderCompactedMessage` to keep them visually distinct.
+ *
+ * If `original` does not contain a `# Conversation Messages` section,
+ * the original prompt is returned unchanged.
+ */
+export function serializeTranscriptToPrompt(original, compacted) {
+    const region = locateConversationRegion(original);
+    if (!region)
+        return original;
+    const parts = [];
+    for (const m of compacted.messages) {
+        if (m.role === "system") {
+            // System-role messages were pulled from the prefix or were synthesized
+            // by the compactor. Either way they belong in the system prefix area,
+            // not in the conversation region — but we don't have a clean home for
+            // them here, so we render them as a summary marker inline.
+            const looksLikePrefix = m.content.includes(CONVERSATION_HEADER) ||
+                (region.prefix.length > 0 && region.prefix.includes(m.content));
+            if (looksLikePrefix)
+                continue; // will be re-emitted via region.prefix
+            parts.push(renderCompactedMessage(m));
+            continue;
+        }
+        if (m.role === "user" && region.suffix.length > 0) {
+            // Last message that matches the suffix verbatim is the active turn —
+            // it gets re-emitted via region.suffix below, skip it here.
+            const stripped = m.content.replace(/^\n+/, "");
+            const suffixStripped = region.suffix.replace(/^\n+/, "");
+            if (stripped === suffixStripped)
+                continue;
+        }
+        // Preserved-tail entries arrive with their original raw header line —
+        // they already include `HH:MM (...) [uuid] Name:` so emit verbatim.
+        if (CONVERSATION_LINE_RE.test(m.content.split("\n")[0]?.trim() ?? "")) {
+            parts.push(m.content);
+        }
+        else {
+            parts.push(renderCompactedMessage(m));
+        }
+    }
+    const newRegion = `${CONVERSATION_HEADER}\n${parts.join("\n")}`;
+    return `${region.prefix}${newRegion}${region.suffix.startsWith("\n") ? "" : "\n"}${region.suffix}`;
+}
+/**
+ * Main entry point for runtime conversation-level compaction.
+ *
+ * No-ops when `currentTokens <= targetTokens`. Otherwise parses the prompt,
+ * runs the selected strategy, serializes back, and returns the result.
+ * Always returns; never throws on a parse-failure path (falls back to
+ * the original prompt with `didCompact: false`).
+ */
+export async function applyConversationCompaction(args) {
+    const startedAt = Date.now();
+    const originalTokens = args.currentTokens;
+    if (args.currentTokens <= args.targetTokens) {
+        return {
+            prompt: args.prompt,
+            didCompact: false,
+            originalTokens,
+            compactedTokens: originalTokens,
+            latencyMs: 0,
+            strategy: args.strategy,
+            targetTokens: args.targetTokens,
+            replacementTargetTokens: args.targetTokens,
+        };
+    }
+    const strategyImpl = compactors[args.strategy] ?? naiveSummaryCompactor;
+    const transcript = parsePromptToTranscript(args.prompt);
+    // Bail when the parser had no conversation region to bite into — running
+    // a summarizer on a single user-message blob is wasted spend.
+    if (transcript.metadata?.parseFallback === true) {
+        return {
+            prompt: args.prompt,
+            didCompact: false,
+            originalTokens,
+            compactedTokens: originalTokens,
+            latencyMs: Date.now() - startedAt,
+            strategy: args.strategy,
+            targetTokens: args.targetTokens,
+            replacementTargetTokens: args.targetTokens,
+        };
+    }
+    const systemOffset = transcript.messages[0]?.role === "system" ? 1 : 0;
+    const hasActiveSuffix = Boolean(locateConversationRegion(args.prompt)?.suffix.trim().length);
+    const preserveTail = Math.max(args.preserveTailMessages ?? 6, hasActiveSuffix ? 1 : 0);
+    const boundary = findSafeCompactionBoundary(transcript.messages, preserveTail);
+    const systemPrefix = systemOffset === 1 ? [transcript.messages[0]] : [];
+    const preservedTail = transcript.messages.slice(boundary);
+    const nonCompactableTokens = approxCountTokens([...systemPrefix, ...preservedTail].map((m) => m.content).join("\n"));
+    const minimumReplacementBudget = Math.min(64, args.targetTokens);
+    const replacementTargetTokens = Math.max(minimumReplacementBudget, Math.min(args.targetTokens, args.targetTokens - nonCompactableTokens - 32));
+    const artifact = await strategyImpl.compact(transcript, {
+        targetTokens: replacementTargetTokens,
+        callModel: args.callModel,
+        countTokens: approxCountTokens,
+        preserveTailMessages: preserveTail,
+    });
+    // Reconstruct a transcript = systemPrefix + replacement + preservedTail.
+    // The compactor returned only the replacement; we need to combine with
+    // the boundary it computed. Easiest: re-split the original transcript
+    // and rebuild here.
+    const compactedTranscript = {
+        messages: [
+            ...systemPrefix,
+            ...artifact.replacementMessages,
+            ...preservedTail,
+        ],
+        metadata: transcript.metadata,
+    };
+    const compactedPrompt = serializeTranscriptToPrompt(args.prompt, compactedTranscript);
+    const compactedTokens = Math.ceil(compactedPrompt.length / 4);
+    if (compactedTokens >= originalTokens) {
+        return {
+            prompt: args.prompt,
+            didCompact: false,
+            originalTokens,
+            compactedTokens: originalTokens,
+            latencyMs: Date.now() - startedAt,
+            strategy: args.strategy,
+            targetTokens: args.targetTokens,
+            replacementTargetTokens,
+            artifact: {
+                replacementMessageCount: artifact.replacementMessages.length,
+                stats: artifact.stats,
+            },
+        };
+    }
+    return {
+        prompt: compactedPrompt,
+        didCompact: compactedPrompt !== args.prompt,
+        originalTokens,
+        compactedTokens,
+        latencyMs: Date.now() - startedAt,
+        strategy: args.strategy,
+        targetTokens: args.targetTokens,
+        replacementTargetTokens,
+        artifact: {
+            replacementMessageCount: artifact.replacementMessages.length,
+            stats: artifact.stats,
+        },
+    };
+}
+/**
+ * Message-level companion to `applyConversationCompaction`.
+ *
+ * v5 runtime model calls often pass OpenAI-style `messages` directly instead
+ * of a flattened prompt string. This path avoids lossy prompt parsing and
+ * lets the conversation compactor operate on the role-tagged transcript.
+ */
+export async function applyConversationMessageCompaction(args) {
+    const startedAt = Date.now();
+    const originalTokens = args.currentTokens;
+    if (args.currentTokens <= args.targetTokens) {
+        return {
+            messages: args.messages,
+            didCompact: false,
+            originalTokens,
+            compactedTokens: originalTokens,
+            latencyMs: 0,
+            strategy: args.strategy,
+            targetTokens: args.targetTokens,
+            replacementTargetTokens: args.targetTokens,
+        };
+    }
+    const strategyImpl = compactors[args.strategy] ?? naiveSummaryCompactor;
+    const transcript = { messages: args.messages };
+    const systemOffset = args.messages[0]?.role === "system" ? 1 : 0;
+    const preserveTail = args.preserveTailMessages ?? 6;
+    const boundary = findSafeCompactionBoundary(args.messages, preserveTail);
+    const systemPrefix = systemOffset === 1 ? [args.messages[0]] : [];
+    const preservedTail = args.messages.slice(boundary);
+    const nonCompactableTokens = approxCountTokens([...systemPrefix, ...preservedTail].map((m) => m.content).join("\n"));
+    const minimumReplacementBudget = Math.min(64, args.targetTokens);
+    const replacementTargetTokens = Math.max(minimumReplacementBudget, Math.min(args.targetTokens, args.targetTokens - nonCompactableTokens - 32));
+    const artifact = await strategyImpl.compact(transcript, {
+        targetTokens: replacementTargetTokens,
+        callModel: args.callModel,
+        countTokens: approxCountTokens,
+        preserveTailMessages: preserveTail,
+    });
+    if (artifact.replacementMessages.length === 0) {
+        return {
+            messages: args.messages,
+            didCompact: false,
+            originalTokens,
+            compactedTokens: originalTokens,
+            latencyMs: Date.now() - startedAt,
+            strategy: args.strategy,
+            targetTokens: args.targetTokens,
+            replacementTargetTokens,
+            artifact: {
+                replacementMessageCount: 0,
+                stats: artifact.stats,
+            },
+        };
+    }
+    const compactedMessages = [
+        ...systemPrefix,
+        ...artifact.replacementMessages,
+        ...preservedTail,
+    ];
+    const compactedTokens = countTranscriptTokens({ messages: compactedMessages }, approxCountTokens);
+    if (compactedTokens >= originalTokens) {
+        return {
+            messages: args.messages,
+            didCompact: false,
+            originalTokens,
+            compactedTokens: originalTokens,
+            latencyMs: Date.now() - startedAt,
+            strategy: args.strategy,
+            targetTokens: args.targetTokens,
+            replacementTargetTokens,
+            artifact: {
+                replacementMessageCount: artifact.replacementMessages.length,
+                stats: artifact.stats,
+            },
+        };
+    }
+    return {
+        messages: compactedMessages,
+        didCompact: true,
+        originalTokens,
+        compactedTokens,
+        latencyMs: Date.now() - startedAt,
+        strategy: args.strategy,
+        targetTokens: args.targetTokens,
+        replacementTargetTokens,
+        artifact: {
+            replacementMessageCount: artifact.replacementMessages.length,
+            stats: artifact.stats,
+        },
+    };
+}

package/packages/agent/src/runtime/conversation-compactor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Conversation-history compactors.
+ *
+ * Implements the four CompactBench strategies (https://github.com/compactbench/compactbench)
+ * — naive-summary, structured-state, hierarchical-summary, hybrid-ledger —
+ * against the shared contract in conversation-compactor.types.ts.
+ *
+ * Distinct from prompt-compaction.ts which strips presentation-layer sections
+ * from a single prompt string. This module operates over multi-turn message
+ * arrays and uses an LLM to summarize the older portion of the transcript
+ * while preserving:
+ *   - the system prompt at index 0 (verbatim, never summarized)
+ *   - the trailing N messages (default 6) verbatim
+ *   - tool_call / tool_result pairing across the boundary
+ */
+import { type Compactor, type CompactorMessage } from "./conversation-compactor.types.ts";
+/**
+ * Identify the index that splits compacted-region (indices < boundary) from
+ * preserved-tail (indices >= boundary), shifting the boundary outward (toward
+ * older messages, i.e. lower indices) until no tool_call / tool_result pair
+ * is split across it.
+ *
+ * Index 0 is reserved when present as a system prompt and is always retained
+ * outside the compactable region — callers should treat indices [1, boundary)
+ * as the region to summarize.
+ *
+ * Returns an integer in [systemOffset, messages.length].
+ *
+ *   - boundary === messages.length  ⇒ nothing to compact (tail covers all).
+ *   - boundary <= systemOffset      ⇒ nothing to compact (everything preserved).
+ */
+export declare function findSafeCompactionBoundary(messages: CompactorMessage[], preserveTailMessages?: number): number;
+export declare const naiveSummaryCompactor: Compactor;
+export declare const structuredStateCompactor: Compactor;
+export declare const hierarchicalSummaryCompactor: Compactor;
+export declare const hybridLedgerCompactor: Compactor;
+export declare const compactors: Record<string, Compactor>;
+//# sourceMappingURL=conversation-compactor.d.ts.map

package/packages/agent/src/runtime/conversation-compactor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-compactor.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/conversation-compactor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,gBAAgB,EAMtB,MAAM,mCAAmC,CAAC;AAQ3C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,oBAAoB,GAAE,MAA8B,GACnD,MAAM,CAqFR;AAgkBD,eAAO,MAAM,qBAAqB,EAAE,SAInC,CAAC;AAiQF,eAAO,MAAM,wBAAwB,EAAE,SAItC,CAAC;AAsJF,eAAO,MAAM,4BAA4B,EAAE,SAI1C,CAAC;AAmOF,eAAO,MAAM,qBAAqB,EAAE,SAInC,CAAC;AAMF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAKhD,CAAC"}