@elizaos/agent 2.0.0-beta.2 → 2.0.11-beta.5

package/runtime/boot-telemetry.js

@@ -0,0 +1,198 @@
+/**
+ * Persistent boot + memory telemetry recorder.
+ *
+ * Boot phase timings (from {@link BootTimer.getSummary}) and a periodic RSS
+ * sampler are written as JSON under `<stateDir>/telemetry/` so runtime
+ * performance can be analyzed over time rather than only tailed from logs.
+ *
+ * Telemetry is best-effort and must never affect boot: only the filesystem
+ * writes are guarded, and a failed write logs a single warning. It is disabled
+ * entirely under tests and when `ELIZA_DISABLE_TELEMETRY=1`.
+ *
+ * @module boot-telemetry
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { logger } from "@elizaos/core";
+import { resolveStateDir } from "../config/paths.js";
+const BOOT_DIR = "boot";
+const MEMORY_DIR = "memory";
+const RESTART_DIR = "restart";
+const LATEST_FILE = "latest.json";
+const RESTART_EVENTS_FILE = "events.json";
+/** Keep at most this many of the most recent RSS samples on disk. */
+const MAX_SAMPLES = 240;
+/** Keep at most this many recent boot/(re)start events on disk. */
+const MAX_RESTART_EVENTS = 200;
+/** True when telemetry should not run (tests or explicit opt-out). */
+function telemetryDisabled() {
+    return (process.env.ELIZA_DISABLE_TELEMETRY === "1" ||
+        process.env.NODE_ENV === "test");
+}
+function captureMemory() {
+    const usage = process.memoryUsage();
+    return {
+        rss: usage.rss,
+        heapUsed: usage.heapUsed,
+        heapTotal: usage.heapTotal,
+        external: usage.external,
+        arrayBuffers: usage.arrayBuffers,
+    };
+}
+function bytesToMb(bytes) {
+    return Math.round((bytes / (1024 * 1024)) * 100) / 100;
+}
+function telemetryDir(...segments) {
+    return path.join(resolveStateDir(), "telemetry", ...segments);
+}
+/**
+ * Write `data` as pretty JSON to `<stateDir>/telemetry/<dir>/<file>`, creating
+ * the directory tree first. Only the filesystem work is guarded; a failure logs
+ * a single warning and is otherwise swallowed so telemetry never breaks boot.
+ */
+async function writeTelemetryFile(dir, file, data) {
+    const targetDir = telemetryDir(dir);
+    const targetPath = path.join(targetDir, file);
+    try {
+        await fs.mkdir(targetDir, { recursive: true });
+        await fs.writeFile(targetPath, `${JSON.stringify(data, null, 2)}\n`);
+    }
+    catch (err) {
+        logger.warn(`[boot-telemetry] Failed to write ${targetPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Persist a boot run: enrich the boot summary with process memory + uptime and
+ * write a timestamped record plus `latest.json` under
+ * `<stateDir>/telemetry/boot/`. Returns immediately when telemetry is disabled.
+ * Resolves once the write completes (or fails safely); callers should `void` it
+ * after boot so it never delays readiness.
+ */
+export async function recordBootTelemetry(summary) {
+    if (telemetryDisabled()) {
+        return;
+    }
+    const recordedAt = new Date().toISOString();
+    const record = {
+        ...summary,
+        recordedAt,
+        processUptimeSec: process.uptime(),
+        memory: captureMemory(),
+    };
+    const fileName = `${recordedAt.replace(/[:.]/g, "-")}.json`;
+    await Promise.all([
+        writeTelemetryFile(BOOT_DIR, fileName, record),
+        writeTelemetryFile(BOOT_DIR, LATEST_FILE, record),
+    ]);
+}
+/**
+ * Append a boot/(re)start event to
+ * `<stateDir>/telemetry/restart/events.json` (a bounded rolling array). Unlike
+ * {@link recordBootTelemetry}, which only fires once a boot *completes*, this is
+ * called at the very start of every boot, so a restart storm — where boots never
+ * finish — is still countable. The dev boot-history endpoint surfaces the array
+ * so an operator can see restart cadence. Best-effort; never throws, never
+ * delays boot (callers should `void` it). Returns immediately when telemetry is
+ * disabled.
+ */
+export async function recordBootEvent(label) {
+    if (telemetryDisabled()) {
+        return;
+    }
+    const spawnedAtMs = Number(process.env.ELIZA_API_PROCESS_SPAWNED_AT_MS);
+    const event = {
+        at: Date.now(),
+        pid: process.pid,
+        spawnedAtMs: Number.isFinite(spawnedAtMs) && spawnedAtMs > 0 ? spawnedAtMs : null,
+        watch: process.env.ELIZA_DEV_NO_WATCH === "0",
+        label,
+    };
+    const targetDir = telemetryDir(RESTART_DIR);
+    const targetPath = path.join(targetDir, RESTART_EVENTS_FILE);
+    try {
+        await fs.mkdir(targetDir, { recursive: true });
+        let events = [];
+        const existing = await fs.readFile(targetPath, "utf8").catch(() => null);
+        if (existing !== null) {
+            try {
+                const parsed = JSON.parse(existing);
+                if (Array.isArray(parsed)) {
+                    events = parsed;
+                }
+            }
+            catch {
+                // Corrupt events file — start fresh; it gets overwritten below.
+                events = [];
+            }
+        }
+        events.push(event);
+        if (events.length > MAX_RESTART_EVENTS) {
+            events.splice(0, events.length - MAX_RESTART_EVENTS);
+        }
+        await fs.writeFile(targetPath, `${JSON.stringify(events, null, 2)}\n`);
+    }
+    catch (err) {
+        logger.warn(`[boot-telemetry] Failed to record boot event: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+let activeSampler = null;
+/**
+ * Begin periodically sampling `process.memoryUsage().rss`, tracking the peak.
+ * On `beforeExit`/`SIGTERM` (or {@link stopMemorySampler}) the run is flushed to
+ * `<stateDir>/telemetry/memory/latest.json`. The interval is `unref()`'d so it
+ * never keeps the process alive. Returns immediately when telemetry is disabled
+ * or a sampler is already running.
+ */
+export function startMemorySampler(options) {
+    if (telemetryDisabled() || activeSampler) {
+        return;
+    }
+    const startedAt = Date.now();
+    const samples = [];
+    let peakRssBytes = 0;
+    const sample = () => {
+        const rss = process.memoryUsage().rss;
+        if (rss > peakRssBytes) {
+            peakRssBytes = rss;
+        }
+        samples.push({ at: Date.now(), rssMb: bytesToMb(rss) });
+        if (samples.length > MAX_SAMPLES) {
+            samples.splice(0, samples.length - MAX_SAMPLES);
+        }
+    };
+    sample();
+    const timer = setInterval(sample, options.intervalMs);
+    timer.unref();
+    const flush = () => {
+        const record = {
+            peakRssMb: bytesToMb(peakRssBytes),
+            startedAt,
+            samples: [...samples],
+        };
+        void writeTelemetryFile(MEMORY_DIR, LATEST_FILE, record);
+    };
+    const onExit = () => {
+        flush();
+    };
+    process.on("beforeExit", onExit);
+    process.on("SIGTERM", onExit);
+    activeSampler = {
+        timer,
+        detach: () => {
+            clearInterval(timer);
+            process.off("beforeExit", onExit);
+            process.off("SIGTERM", onExit);
+            flush();
+        },
+    };
+}
+/** Stop the active memory sampler and flush a final snapshot to disk. */
+export function stopMemorySampler() {
+    if (!activeSampler) {
+        return;
+    }
+    const handle = activeSampler;
+    activeSampler = null;
+    handle.detach();
+}

package/runtime/boot-timer.d.ts

@@ -0,0 +1,41 @@
+/** A single recorded boot phase with its elapsed and cumulative durations. */
+export interface BootLap {
+    /** Phase label passed to `lap()`. */
+    name: string;
+    /** Milliseconds elapsed since the previous lap. */
+    ms: number;
+    /** Milliseconds elapsed since the timer was constructed. */
+    cumulativeMs: number;
+}
+/** Structured snapshot of a boot run, suitable for serialization. */
+export interface BootSummary {
+    /** Timer label, e.g. `[eliza-boot]`. */
+    label: string;
+    /** Total boot duration in milliseconds at the time of the snapshot. */
+    totalMs: number;
+    /** Epoch milliseconds when the timer was constructed. */
+    startedAt: number;
+    /** Laps in the order they were recorded. */
+    laps: BootLap[];
+}
+/**
+ * Lap-based boot phase timer. Each `lap(name)` logs the elapsed time since the
+ * previous lap (and the cumulative time since construction), so dropping a few
+ * one-line `lap()` calls between existing startup statements yields a per-phase
+ * breakdown without restructuring the boot code into closures. `summary()`
+ * prints the laps sorted slowest-first, which is what you read to find the
+ * boot bottleneck. `getSummary()` returns the same data as a structured object
+ * for persistence (see `recordBootTelemetry`).
+ */
+export declare class BootTimer {
+    private readonly label;
+    private readonly start;
+    private last;
+    private readonly laps;
+    constructor(label?: string);
+    lap(name: string): void;
+    /** Structured snapshot of the boot run for telemetry/persistence. */
+    getSummary(): BootSummary;
+    summary(): void;
+}
+//# sourceMappingURL=boot-timer.d.ts.map

package/runtime/boot-timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-timer.d.ts","sourceRoot":"","sources":["../../src/runtime/boot-timer.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,WAAW,OAAO;IACtB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IAKR,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJlC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;gBAET,KAAK,SAAW;IAE7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IASvB,qEAAqE;IACrE,UAAU,IAAI,WAAW;IASzB,OAAO,IAAI,IAAI;CAUhB"}

package/runtime/boot-timer.js

@@ -0,0 +1,42 @@
+import { logger } from "@elizaos/core";
+/**
+ * Lap-based boot phase timer. Each `lap(name)` logs the elapsed time since the
+ * previous lap (and the cumulative time since construction), so dropping a few
+ * one-line `lap()` calls between existing startup statements yields a per-phase
+ * breakdown without restructuring the boot code into closures. `summary()`
+ * prints the laps sorted slowest-first, which is what you read to find the
+ * boot bottleneck. `getSummary()` returns the same data as a structured object
+ * for persistence (see `recordBootTelemetry`).
+ */
+export class BootTimer {
+    label;
+    start = Date.now();
+    last = this.start;
+    laps = [];
+    constructor(label = "[boot]") {
+        this.label = label;
+    }
+    lap(name) {
+        const now = Date.now();
+        const ms = now - this.last;
+        this.last = now;
+        const cumulativeMs = now - this.start;
+        this.laps.push({ name, ms, cumulativeMs });
+        logger.info(`${this.label} ${name}: ${ms}ms (t+${cumulativeMs}ms)`);
+    }
+    /** Structured snapshot of the boot run for telemetry/persistence. */
+    getSummary() {
+        return {
+            label: this.label,
+            totalMs: Date.now() - this.start,
+            startedAt: this.start,
+            laps: this.laps.map((lap) => ({ ...lap })),
+        };
+    }
+    summary() {
+        const { totalMs, laps } = this.getSummary();
+        const slowest = [...laps].sort((a, b) => b.ms - a.ms);
+        const lines = slowest.map((p) => `    ${String(p.ms).padStart(7)}ms  ${p.name}`);
+        logger.info(`${this.label} boot phase summary (total ${totalMs}ms, slowest first):\n${lines.join("\n")}`);
+    }
+}

package/runtime/build-character-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-character-config.d.ts","sourceRoot":"","sources":["../../src/runtime/build-character-config.ts"],"names":[],"mappings":""}

package/runtime/build-character-config.js

@@ -0,0 +1,220 @@
+import { defaultCharacterSystemTemplate, mergeCharacterDefaults, } from "@elizaos/core";
+import { getDefaultStylePreset, normalizeCharacterLanguage, resolveStylePresetByAvatarIndex, resolveStylePresetById, resolveStylePresetByName, } from "@elizaos/shared";
+import { applyAdvancedCapabilitySettings, resolveAdvancedCapabilitiesEnabled, } from "./advanced-capabilities-config.js";
+/**
+ * Build a Character object from the runtime ElizaConfig.
+ *
+ * The character is the initial runtime identity — name, bio, system prompt,
+ * secrets, and capability settings. It is NOT the persisted agent record in the
+ * database — not the config file — so we only provide sensible defaults here
+ * for the initial setup.
+ */
+/** @internal Exported for testing. */
+export function buildCharacterFromConfig(config) {
+    const agentEntry = config.agents?.list?.[0];
+    const uiConfig = (config.ui ?? {});
+    const language = normalizeCharacterLanguage(uiConfig.language);
+    const configuredUiName = uiConfig.assistant?.name?.trim();
+    const configuredAgentName = agentEntry?.name?.trim();
+    // Prefer the UI-level assistant name when it diverges from the bundled
+    // preset entry so renames take effect immediately across prompts/logging.
+    const configuredName = configuredUiName || configuredAgentName;
+    const bundledPreset = resolveStylePresetById(uiConfig.presetId, language) ??
+        resolveStylePresetByAvatarIndex(uiConfig.avatarIndex, language) ??
+        resolveStylePresetByName(configuredName, language) ??
+        (configuredName ? undefined : getDefaultStylePreset(language));
+    const name = configuredName ??
+        bundledPreset?.name ??
+        getDefaultStylePreset(language).name;
+    const bio = agentEntry?.bio ??
+        bundledPreset?.bio ?? [
+        "{{name}} is an AI assistant powered by Eliza and elizaOS.",
+    ];
+    const systemPrompt = agentEntry?.system ??
+        bundledPreset?.system ??
+        defaultCharacterSystemTemplate;
+    const style = agentEntry?.style ?? bundledPreset?.style;
+    const adjectives = agentEntry?.adjectives ?? bundledPreset?.adjectives;
+    const topics = agentEntry?.topics && agentEntry.topics.length > 0
+        ? agentEntry.topics
+        : bundledPreset?.topics;
+    const postExamples = agentEntry?.postExamples ?? bundledPreset?.postExamples;
+    const messageExamples = agentEntry?.messageExamples ?? bundledPreset?.messageExamples;
+    const advancedMemory = agentEntry?.advancedMemory ??
+        config.agents?.defaults?.advancedMemory ??
+        true;
+    // Lean cloud chat agents (ELIZA_PLUGIN_SET=lean-chat) skip advanced
+    // capabilities. The reflection/fact/relationship/identity evaluators they
+    // register fan out a SERIAL cloud-embedding call per extracted item every
+    // turn (measured ~7 x ~1.5s = the bulk of a dedicated chat agent's wall-clock
+    // after the DB-locality fix). A purely conversational agent still keeps raw
+    // message/reply memory; it just doesn't run the structured post-turn
+    // extraction. Scoped strictly to the lean-chat flag, so desktop/mobile/
+    // non-cloud agents (no ELIZA_PLUGIN_SET) keep advanced capabilities on.
+    const advancedCapabilitiesEnabled = process.env.ELIZA_PLUGIN_SET?.trim().toLowerCase() === "lean-chat"
+        ? false
+        : resolveAdvancedCapabilitiesEnabled(config);
+    const settings = applyAdvancedCapabilitySettings({
+        MEMORY_SUMMARY_MODEL_TYPE: process.env.MEMORY_SUMMARY_MODEL_TYPE?.trim() || "TEXT_SMALL",
+        MEMORY_REFLECTION_MODEL_TYPE: process.env.MEMORY_REFLECTION_MODEL_TYPE?.trim() || "TEXT_LARGE",
+    }, advancedCapabilitiesEnabled);
+    // Collect secrets from process.env (API keys the plugins need)
+    const secretKeys = [
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+        "GEMINI_API_KEY",
+        "GOOGLE_API_KEY",
+        "GOOGLE_GENERATIVE_AI_API_KEY",
+        "GROQ_API_KEY",
+        "XAI_API_KEY",
+        "OPENROUTER_API_KEY",
+        "AI_GATEWAY_API_KEY",
+        "AIGATEWAY_API_KEY",
+        "AI_GATEWAY_BASE_URL",
+        "AI_GATEWAY_SMALL_MODEL",
+        "AI_GATEWAY_LARGE_MODEL",
+        "AI_GATEWAY_EMBEDDING_MODEL",
+        "AI_GATEWAY_EMBEDDING_DIMENSIONS",
+        "AI_GATEWAY_IMAGE_MODEL",
+        "AI_GATEWAY_TIMEOUT_MS",
+        "OLLAMA_BASE_URL",
+        "DISCORD_API_TOKEN",
+        "DISCORD_APPLICATION_ID",
+        "DISCORD_BOT_TOKEN",
+        "TELEGRAM_BOT_TOKEN",
+        "WHATSAPP_ACCESS_TOKEN",
+        "WHATSAPP_PHONE_NUMBER_ID",
+        "WHATSAPP_AUTH_DIR",
+        "WHATSAPP_SESSION_PATH",
+        "WHATSAPP_WEBHOOK_VERIFY_TOKEN",
+        "WHATSAPP_API_VERSION",
+        "WHATSAPP_DM_POLICY",
+        "WHATSAPP_GROUP_POLICY",
+        "WHATSAPP_ALLOW_FROM",
+        "WHATSAPP_GROUP_ALLOW_FROM",
+        "TELEGRAM_ACCOUNT_PHONE",
+        "TELEGRAM_ACCOUNT_APP_ID",
+        "TELEGRAM_ACCOUNT_APP_HASH",
+        "TELEGRAM_ACCOUNT_DEVICE_MODEL",
+        "TELEGRAM_ACCOUNT_SYSTEM_VERSION",
+        "SLACK_BOT_TOKEN",
+        "SLACK_APP_TOKEN",
+        "SLACK_USER_TOKEN",
+        "SIGNAL_ACCOUNT_NUMBER",
+        "MSTEAMS_APP_ID",
+        "MSTEAMS_APP_PASSWORD",
+        "MATTERMOST_BOT_TOKEN",
+        "MATTERMOST_BASE_URL",
+        // Matrix connector — only the genuine credentials live here (redactable
+        // secrets). The homeserver URL, user/room/device IDs, the verify-allowlist,
+        // and the behaviour flags are PUBLIC identifiers and are bridged as plain
+        // settings below (matrixPublicConfigKeys) — putting them in secrets makes the
+        // redaction layer blank them out wherever they appear in output (e.g. a DM
+        // room name "remilio ↔ @user:server" rendered as "[REDACTED:...]").
+        // MATRIX_ACCOUNTS stays a secret because its JSON embeds per-account tokens.
+        "MATRIX_ACCESS_TOKEN",
+        "MATRIX_PASSWORD",
+        "MATRIX_ACCOUNTS",
+        // ElizaCloud secrets
+        "ELIZAOS_CLOUD_API_KEY",
+        "ELIZAOS_CLOUD_BASE_URL",
+        "ELIZAOS_CLOUD_ENABLED",
+        // Wallet / blockchain secrets
+        "EVM_PRIVATE_KEY",
+        "SOLANA_PRIVATE_KEY",
+        "ALCHEMY_API_KEY",
+        "HELIUS_API_KEY",
+        "BIRDEYE_API_KEY",
+        "SOLANA_RPC_URL",
+        "X402_PRIVATE_KEY",
+        "X402_NETWORK",
+        "X402_PAY_TO",
+        "X402_FACILITATOR_URL",
+        "X402_MAX_PAYMENT_USD",
+        "X402_MAX_TOTAL_USD",
+        "X402_ENABLED",
+        "X402_DB_PATH",
+        // GitHub access for coding agent plugin
+        "GITHUB_TOKEN",
+        "GITHUB_OAUTH_CLIENT_ID",
+    ];
+    const secrets = {};
+    for (const key of secretKeys) {
+        const value = process.env[key];
+        if (value?.trim()) {
+            secrets[key] = value;
+        }
+    }
+    // Public connector identifiers + behaviour flags: bridged as plain settings so
+    // getSetting() still resolves them (settings is checked before env in
+    // getSetting), but the secrets-redaction layer — which only scans
+    // character.settings.secrets — leaves them intact. These are not credentials
+    // (homeserver URL, user/room/device IDs, the verify allow-list, on/off flags),
+    // so redacting them only corrupted output (room names, the agent's own id).
+    const matrixPublicConfigKeys = [
+        "MATRIX_HOMESERVER",
+        "MATRIX_USER_ID",
+        "MATRIX_DEVICE_ID",
+        "MATRIX_ROOMS",
+        "MATRIX_AUTO_JOIN",
+        "MATRIX_AUTO_REPLY",
+        "MATRIX_ENCRYPTION",
+        "MATRIX_REQUIRE_MENTION",
+        "MATRIX_VERIFY_ALLOWLIST",
+        "MATRIX_PERSONAL",
+    ];
+    for (const key of matrixPublicConfigKeys) {
+        const value = process.env[key];
+        if (value?.trim()) {
+            settings[key] = value;
+        }
+    }
+    // Normalise messageExamples to the {examples: [{name,content}]} shape
+    // that @elizaos/core expects.  Config may contain EITHER format:
+    //   OLD (preset/first-run): [[{user, content}, ...], ...]
+    //   NEW (@elizaos/core):     [{examples: [{name, content}, ...]}, ...]
+    const mappedExamples = messageExamples?.map((item) => {
+        // Already in new format — pass through
+        if (item &&
+            typeof item === "object" &&
+            "examples" in item) {
+            return item;
+        }
+        // Old format — array of {user, content} entries
+        const arr = item;
+        return {
+            examples: arr.map((msg) => ({
+                name: msg.name ?? msg.user ?? "",
+                content: msg.content,
+            })),
+        };
+    });
+    // Capability hints — append short descriptions of features the runtime has
+    // auto-enabled so the model knows about new actions/tools without requiring
+    // the user to hand-edit the system prompt. Kept terse (one sentence per
+    // capability) to stay out of the way of the preset's voice.
+    const capabilityHints = [];
+    const workflowMasterEnabled = config.workflow?.enabled !== false;
+    const workflowExplicitlyDisabled = config.plugins?.entries?.workflow?.enabled === false;
+    if (workflowMasterEnabled && !workflowExplicitlyDisabled) {
+        capabilityHints.push("You can create, activate, deactivate, and delete workflows via natural language using the workflow actions.");
+    }
+    capabilityHints.push("You have a persistent task manager and can create scheduled or one-off tasks when the user asks; do not claim you lack tasks, memory, persistence, or scheduling when those actions are available.");
+    const effectiveSystemPrompt = capabilityHints.length > 0
+        ? `${systemPrompt}\n\n${capabilityHints.join("\n")}`
+        : systemPrompt;
+    return mergeCharacterDefaults({
+        name,
+        ...(agentEntry?.username ? { username: agentEntry.username } : {}),
+        bio,
+        system: effectiveSystemPrompt,
+        ...(topics ? { topics } : {}),
+        ...(style ? { style } : {}),
+        ...(adjectives ? { adjectives } : {}),
+        ...(postExamples ? { postExamples } : {}),
+        ...(mappedExamples ? { messageExamples: mappedExamples } : {}),
+        advancedMemory,
+        settings,
+        secrets,
+    });
+}

package/runtime/conversation-compactor-runtime.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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.
+ *
+ * Enabled by default with the hybrid-ledger strategy. Set
+ * `ELIZA_CONVERSATION_COMPACTOR=off|none|false|0|disabled` to disable, or set
+ * it to a named strategy to override.
+ *
+ * The preferred path is the message-history hook installed at runtime,
+ * which compacts structured RECENT_MESSAGES state before prompt rendering.
+ * The string parse/serialize path remains as a conservative fallback for
+ * direct prompt calls that do not pass through message-state composition.
+ */
+import type { AgentRuntime, JsonValue, Memory, MessageHistoryCompactionHookResult, State } 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];
+export declare const DEFAULT_CONVERSATION_COMPACTOR_STRATEGY: StrategyName;
+/**
+ * Reads `ELIZA_CONVERSATION_COMPACTOR` from the environment.
+ * Returns the default strategy when unset.
+ * Returns `null` when explicitly disabled.
+ * Throws when set to a value that is not a known strategy name.
+ */
+export declare function selectStrategyFromEnv(): StrategyName | null;
+export declare function getConversationCompactionLedger(runtime: AgentRuntime, conversationKey: string | undefined): Promise<string | null>;
+export declare function setConversationCompactionLedger(runtime: AgentRuntime, conversationKey: string | undefined, ledger: string, options?: {
+    strategy?: StrategyName | null;
+    source?: string;
+    lastCompactionAt?: number;
+    historyEntry?: Record<string, JsonValue>;
+}): Promise<void>;
+/**
+ * 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 return safely with 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;
+    /** Optional metadata forwarded to the compactor (for prior ledgers, ids). */
+    metadata?: Record<string, unknown>;
+};
+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;
+    };
+    skipReason?: string;
+};
+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;
+    /** Optional metadata forwarded to the compactor (for prior ledgers, ids). */
+    metadata?: Record<string, unknown>;
+};
+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.
+ *
+ * Returns the original prompt 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 declare function applyMessageHistoryCompactionToState(args: {
+    runtime: AgentRuntime;
+    message: Memory;
+    state: State;
+    source?: "compose-response-state" | "provider-grounded-state" | "continuation-state";
+    callModel: CompactorModelCall;
+}): Promise<MessageHistoryCompactionHookResult>;
+export declare function installMessageHistoryCompactionHook(runtime: AgentRuntime, options?: {
+    originalUseModel?: AgentRuntime["useModel"] | null;
+}): void;
+export {};
+//# sourceMappingURL=conversation-compactor-runtime.d.ts.map