qlogicagent 2.13.3 → 2.13.5

package/dist/runtime/config/tunable-defaults.js

@@ -0,0 +1,293 @@
+/**
+ * Centralized tunable defaults — single source of truth.
+ *
+ * ALL configurable constants that external apps (Electron UI, CLI config)
+ * may want to read or override are defined here. This enables:
+ *
+ * 1. A future `config.tunables` RPC endpoint for visual editing
+ * 2. Serialization to JSON for persistence (settings.json)
+ * 3. Environment variable overrides via QLOGICAGENT_* prefix
+ *
+ * Consumers import individual constants from this module.
+ * The full shape is exported as `TunableDefaults` interface for RPC typing.
+ *
+ * Grouping follows subsystem boundaries.
+ */
+// ══════════════════════════════════════════════════════════════
+// 1. Agent Loop — core turn execution
+// ══════════════════════════════════════════════════════════════
+/** Absolute max rounds any agent can run (hard cap). */
+export const MAX_ROUNDS_LIMIT = 100;
+/** Default rounds for a top-level agent turn. */
+export const DEFAULT_MAX_ROUNDS = 25;
+/** Default temperature for LLM calls (0 = deterministic). */
+export const DEFAULT_TEMPERATURE = 0;
+/** Hard cap on tool calls per round (prevents runaway). */
+export const MAX_TOOL_BUDGET_CAP = 100;
+/** Default tool budget per round. Overridable via TOOL_LOOP_DEFAULT_BUDGET env. */
+export const DEFAULT_TOOL_BUDGET = Math.min(Math.max(1, Number(process.env.TOOL_LOOP_DEFAULT_BUDGET) || 25), MAX_TOOL_BUDGET_CAP);
+/** Max consecutive tool call failures before early exit. */
+export const MAX_CONSECUTIVE_FAILURES = 3;
+/** Max times the exact same (tool_name, arguments) pair can repeat. */
+export const MAX_IDENTICAL_CALL_REPEATS = 2;
+/** Max times the same tool can fail with different args before blocking (variant-loop detection).
+ *  Includes both hard failures (ok=false) and soft empty results (e.g. "No matches found").
+ *  Note: blocked calls still emit tool_call events, so effective max attempts visible to
+ *  client = MAX + 1 (the blocked attempt) + possible 1 alternative tool = MAX + 2. */
+export const MAX_TOOL_VARIANT_FAILURES = 2;
+// ══════════════════════════════════════════════════════════════
+// 2. Token Budget — context window management
+// ══════════════════════════════════════════════════════════════
+/** Default context window size (tokens). */
+export const DEFAULT_CONTEXT_WINDOW_TOKENS = 128_000;
+/** Reserved tokens for model response output. */
+export const RESPONSE_BUFFER_TOKENS = 13_000;
+/** Default max output tokens per LLM API call. */
+export const DEFAULT_MAX_OUTPUT_TOKENS = 16_384;
+/** Model's absolute max output tokens (escalation ceiling). */
+export const DEFAULT_MODEL_MAX_OUTPUT_TOKENS = 65_536;
+/** Max max_output_tokens recovery attempts (CC: 3). */
+export const MAX_OUTPUT_TOKENS_RECOVERY_LIMIT = 3;
+/** Escalated max output tokens during recovery (CC: 64k). */
+export const ESCALATED_MAX_OUTPUT_TOKENS = 65_536;
+/** Delta threshold for "diminishing returns" detection (CC: 500). */
+export const DIMINISHING_RETURNS_THRESHOLD = 500;
+/** Min consecutive continuations before diminishing returns kicks in. */
+export const DIMINISHING_RETURNS_MIN_CONTINUATIONS = 3;
+// ══════════════════════════════════════════════════════════════
+// 3. Tool Result — persistence & budget
+// ══════════════════════════════════════════════════════════════
+/** Per-tool result size threshold (chars) for disk persistence. */
+export const DEFAULT_MAX_RESULT_SIZE_CHARS = 50_000;
+/** Per-message aggregate tool result budget (chars). */
+export const MAX_TOOL_RESULTS_PER_MESSAGE_CHARS = 200_000;
+/** Preview size for persisted tool result references (bytes). */
+export const TOOL_RESULT_PREVIEW_BYTES = 2_000;
+// ══════════════════════════════════════════════════════════════
+// 4. Persistent Retry — CC withRetry.ts parity
+// ══════════════════════════════════════════════════════════════
+/** Heartbeat interval during persistent retry waits (ms). */
+export const HEARTBEAT_INTERVAL_MS = 30_000;
+/** Max 529 errors before fallback model switch. */
+export const MAX_529_RETRIES = 3;
+/** Max consecutive API error retries before aborting. */
+export const MAX_API_RETRIES = 2;
+/** Max backoff interval for persistent retry (ms). */
+export const PERSISTENT_RETRY_MAX_BACKOFF_MS = 300_000;
+/** Total retry time cap for persistent retry (ms). */
+export const PERSISTENT_RETRY_RESET_CAP_MS = 21_600_000;
+// ══════════════════════════════════════════════════════════════
+// 5. Context Compression — adaptive budget
+// ══════════════════════════════════════════════════════════════
+/** Target usage ratio after compression (0-1). */
+export const COMPRESSION_TARGET_USAGE_RATIO = 0.75;
+/** Min token budget floor after compression. */
+export const COMPRESSION_MIN_BUDGET = 16_000;
+/** Max token budget ceiling. */
+export const COMPRESSION_MAX_BUDGET = 120_000;
+/** Max consecutive reactive compaction failures. */
+export const REACTIVE_COMPACT_MAX_FAILURES = 3;
+/** Min messages to keep after reactive compaction. */
+export const REACTIVE_COMPACT_MIN_MESSAGES = 4;
+/** Target usage percentage for reactive compaction. */
+export const REACTIVE_COMPACT_TARGET_PERCENT = 50;
+// ══════════════════════════════════════════════════════════════
+// 6. Skill System — proliferation control & injection
+// ══════════════════════════════════════════════════════════════
+/** Max auto-learned skills per project. */
+export const MAX_SKILLS_PER_PROJECT = 20;
+/** Max global (user-level) skills. */
+export const MAX_SKILLS_GLOBAL = 50;
+/** Min tool calls to consider a turn "complex enough" for skill creation. */
+export const MIN_TOOL_CALLS_FOR_SKILL = 3;
+/** Min distinct tools to suggest a new skill. */
+export const MIN_DISTINCT_TOOLS_FOR_SKILL = 2;
+/** Cooldown between skill creation suggestions (ms). */
+export const SKILL_CREATION_COOLDOWN_MS = 5 * 60 * 1000;
+/**
+ * Project-level pattern repetition threshold.
+ * The same workflow signature must appear this many times across turns/sessions
+ * before a skill creation is triggered. Prevents one-off complex turns from
+ * immediately producing skills.
+ */
+export const SKILL_PATTERN_REPETITION_THRESHOLD = 3;
+/**
+ * Max age (ms) for pattern entries. Patterns older than this are pruned.
+ * Default: 30 days.
+ */
+export const SKILL_PATTERN_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/** Max chars of skill content injected into system prompt. */
+export const SKILL_INJECTION_MAX_CHARS = 4_000;
+/** Max skills injected into a single prompt. */
+export const SKILL_INJECTION_MAX_COUNT = 5;
+/** Max skills recalled from other projects per turn. */
+export const SKILL_RECALL_MAX_SKILLS = 3;
+/** Max chars per recalled skill content. */
+export const SKILL_RECALL_MAX_CONTENT_CHARS = 800;
+/** Skill recall index cache TTL (ms). */
+export const SKILL_RECALL_CACHE_TTL_MS = 5 * 60 * 1000;
+// ══════════════════════════════════════════════════════════════
+// 7. Sub-Agent — fork/delegation
+// ══════════════════════════════════════════════════════════════
+/** Max nested fork depth for sub-agents. */
+export const MAX_FORK_DEPTH = 4;
+/** Team aggregate budget (total tokens across all forked sub-agents). 0 = unlimited. */
+export const TEAM_BUDGET_TOKENS = 0;
+// ══════════════════════════════════════════════════════════════
+// 8. Session & Persistence
+// ══════════════════════════════════════════════════════════════
+/** Max historical sessions retained on disk. */
+export const MAX_SESSIONS = 50;
+/** Turn count threshold for triggering task summary. */
+export const TASK_SUMMARY_TURN_THRESHOLD = 50;
+/** Interval (turns) between summary regeneration. */
+export const TASK_SUMMARY_REGEN_INTERVAL = 30;
+/** Idle duration (ms) before a group session is auto-split into a new session. Default: 1 hour. */
+export const GROUP_SESSION_IDLE_THRESHOLD_MS = 1 * 60 * 60 * 1000;
+/** Hard limit: max turns in a single group session before soft-split. Default: 200 turns. */
+export const GROUP_SESSION_MAX_TURNS = 200;
+// ══════════════════════════════════════════════════════════════
+// 9. Instructions — loader & store limits
+// ══════════════════════════════════════════════════════════════
+/** Max include nesting depth in instruction files. */
+export const MAX_INCLUDE_DEPTH = 5;
+/** Max total chars loaded from instruction files. */
+export const MAX_INSTRUCTION_CHARS = 40_000;
+/** Max single instruction file size (bytes). */
+export const INSTRUCTIONS_MAX_FILE_SIZE = 50 * 1024;
+/** Max total instruction directory size (bytes). */
+export const INSTRUCTIONS_MAX_DIR_SIZE = 500 * 1024;
+// ══════════════════════════════════════════════════════════════
+// 10. Media — download & persistence
+// ══════════════════════════════════════════════════════════════
+/** Max single media file download size (bytes, 500 MB). */
+export const MEDIA_MAX_DOWNLOAD_SIZE = 500 * 1024 * 1024;
+/** Max file size for direct LLM upload (bytes, 50 MB).
+ *  Files larger than this should be chunked or summarized before sending to LLM. */
+export const MEDIA_MAX_UPLOAD_SIZE = 50 * 1024 * 1024;
+/** Media download timeout (ms). */
+export const MEDIA_DOWNLOAD_TIMEOUT_MS = 300_000;
+// ══════════════════════════════════════════════════════════════
+// 11. ACP Agent Process — spawn & restart
+// ══════════════════════════════════════════════════════════════
+/** Max retries when spawning an ACP agent process. */
+export const ACP_MAX_SPAWN_RETRIES = 2;
+/** Backoff base for agent spawn retries (ms). */
+export const ACP_RETRY_BACKOFF_BASE = 3_000;
+/** Max automatic restarts after agent process crash. */
+export const ACP_RUNTIME_RESTART_MAX = 3;
+/** Backoff base for crash restarts (ms). */
+export const ACP_RUNTIME_RESTART_BACKOFF_BASE = 5_000;
+// ══════════════════════════════════════════════════════════════
+// 12. Task Runtime — polling & display
+// ══════════════════════════════════════════════════════════════
+/** Running task poll interval (ms). */
+export const TASK_POLL_INTERVAL_MS = 1_000;
+/** How long to display stopped tasks before removal (ms). */
+export const TASK_STOPPED_DISPLAY_MS = 3_000;
+/** Terminal task cleanup grace period (ms). */
+export const TASK_PANEL_GRACE_MS = 30_000;
+// ══════════════════════════════════════════════════════════════
+// 13. Memory — prefetch & dream consolidation
+// ══════════════════════════════════════════════════════════════
+/** Max bytes injected for session memory prefetch. */
+export const MEMORY_PREFETCH_MAX_SESSION_BYTES = 60 * 1024;
+/** Max results per memory recall query. */
+export const MEMORY_PREFETCH_LIMIT_PER_RECALL = 10;
+/** LRU dedup set size for surfaced memory entries. */
+export const MEMORY_MAX_SURFACED_ENTRIES = 100;
+/** Min hours between dream consolidation runs. */
+export const DREAM_MIN_INTERVAL_HOURS = 24;
+/** Min sessions before dream triggers. */
+export const DREAM_MIN_SESSIONS = 5;
+/** Dream scan throttle interval (ms). */
+export const DREAM_SCAN_INTERVAL_MS = 600_000;
+/** Idle dream timer (minutes). */
+export const IDLE_DREAM_MINUTES = 30;
+/** Dream cooldown between runs (ms, 4 hours). */
+export const DREAM_COOLDOWN_MS = 14_400_000;
+/** Max dream run duration (ms). */
+export const DREAM_MAX_DURATION_MS = 300_000;
+/**
+ * Snapshot of all current tunable values.
+ * Use this for RPC serialization and external app display.
+ */
+export function getTunableDefaults() {
+    return {
+        maxRoundsLimit: MAX_ROUNDS_LIMIT,
+        defaultMaxRounds: DEFAULT_MAX_ROUNDS,
+        defaultTemperature: DEFAULT_TEMPERATURE,
+        maxToolBudgetCap: MAX_TOOL_BUDGET_CAP,
+        defaultToolBudget: DEFAULT_TOOL_BUDGET,
+        maxConsecutiveFailures: MAX_CONSECUTIVE_FAILURES,
+        maxIdenticalCallRepeats: MAX_IDENTICAL_CALL_REPEATS,
+        defaultContextWindowTokens: DEFAULT_CONTEXT_WINDOW_TOKENS,
+        responseBufferTokens: RESPONSE_BUFFER_TOKENS,
+        defaultMaxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+        defaultModelMaxOutputTokens: DEFAULT_MODEL_MAX_OUTPUT_TOKENS,
+        maxOutputTokensRecoveryLimit: MAX_OUTPUT_TOKENS_RECOVERY_LIMIT,
+        escalatedMaxOutputTokens: ESCALATED_MAX_OUTPUT_TOKENS,
+        diminishingReturnsThreshold: DIMINISHING_RETURNS_THRESHOLD,
+        diminishingReturnsMinContinuations: DIMINISHING_RETURNS_MIN_CONTINUATIONS,
+        defaultMaxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+        maxToolResultsPerMessageChars: MAX_TOOL_RESULTS_PER_MESSAGE_CHARS,
+        toolResultPreviewBytes: TOOL_RESULT_PREVIEW_BYTES,
+        heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+        max529Retries: MAX_529_RETRIES,
+        maxApiRetries: MAX_API_RETRIES,
+        persistentRetryMaxBackoffMs: PERSISTENT_RETRY_MAX_BACKOFF_MS,
+        persistentRetryResetCapMs: PERSISTENT_RETRY_RESET_CAP_MS,
+        compressionTargetUsageRatio: COMPRESSION_TARGET_USAGE_RATIO,
+        compressionMinBudget: COMPRESSION_MIN_BUDGET,
+        compressionMaxBudget: COMPRESSION_MAX_BUDGET,
+        reactiveCompactMaxFailures: REACTIVE_COMPACT_MAX_FAILURES,
+        reactiveCompactMinMessages: REACTIVE_COMPACT_MIN_MESSAGES,
+        reactiveCompactTargetPercent: REACTIVE_COMPACT_TARGET_PERCENT,
+        maxSkillsPerProject: MAX_SKILLS_PER_PROJECT,
+        maxSkillsGlobal: MAX_SKILLS_GLOBAL,
+        minToolCallsForSkill: MIN_TOOL_CALLS_FOR_SKILL,
+        minDistinctToolsForSkill: MIN_DISTINCT_TOOLS_FOR_SKILL,
+        skillCreationCooldownMs: SKILL_CREATION_COOLDOWN_MS,
+        skillInjectionMaxChars: SKILL_INJECTION_MAX_CHARS,
+        skillInjectionMaxCount: SKILL_INJECTION_MAX_COUNT,
+        skillRecallMaxSkills: SKILL_RECALL_MAX_SKILLS,
+        skillRecallMaxContentChars: SKILL_RECALL_MAX_CONTENT_CHARS,
+        skillRecallCacheTtlMs: SKILL_RECALL_CACHE_TTL_MS,
+        maxForkDepth: MAX_FORK_DEPTH,
+        maxSessions: MAX_SESSIONS,
+        taskSummaryTurnThreshold: TASK_SUMMARY_TURN_THRESHOLD,
+        taskSummaryRegenInterval: TASK_SUMMARY_REGEN_INTERVAL,
+        maxIncludeDepth: MAX_INCLUDE_DEPTH,
+        maxInstructionChars: MAX_INSTRUCTION_CHARS,
+        instructionsMaxFileSize: INSTRUCTIONS_MAX_FILE_SIZE,
+        instructionsMaxDirSize: INSTRUCTIONS_MAX_DIR_SIZE,
+        mediaMaxDownloadSize: MEDIA_MAX_DOWNLOAD_SIZE,
+        mediaMaxUploadSize: MEDIA_MAX_UPLOAD_SIZE,
+        mediaDownloadTimeoutMs: MEDIA_DOWNLOAD_TIMEOUT_MS,
+        acpMaxSpawnRetries: ACP_MAX_SPAWN_RETRIES,
+        acpRetryBackoffBase: ACP_RETRY_BACKOFF_BASE,
+        acpRuntimeRestartMax: ACP_RUNTIME_RESTART_MAX,
+        acpRuntimeRestartBackoffBase: ACP_RUNTIME_RESTART_BACKOFF_BASE,
+        taskPollIntervalMs: TASK_POLL_INTERVAL_MS,
+        taskStoppedDisplayMs: TASK_STOPPED_DISPLAY_MS,
+        taskPanelGraceMs: TASK_PANEL_GRACE_MS,
+        memoryPrefetchMaxSessionBytes: MEMORY_PREFETCH_MAX_SESSION_BYTES,
+        memoryPrefetchLimitPerRecall: MEMORY_PREFETCH_LIMIT_PER_RECALL,
+        memoryMaxSurfacedEntries: MEMORY_MAX_SURFACED_ENTRIES,
+        dreamMinIntervalHours: DREAM_MIN_INTERVAL_HOURS,
+        dreamMinSessions: DREAM_MIN_SESSIONS,
+        dreamScanIntervalMs: DREAM_SCAN_INTERVAL_MS,
+        idleDreamMinutes: IDLE_DREAM_MINUTES,
+        dreamCooldownMs: DREAM_COOLDOWN_MS,
+        dreamMaxDurationMs: DREAM_MAX_DURATION_MS,
+        teamBudgetTokens: TEAM_BUDGET_TOKENS,
+        // Web search sources: declared so the UI tunables page and the config
+        // tool can manage them (consumers read via getTunable, env fallback).
+        braveApiKey: "",
+        exaApiKey: "",
+        serperApiKey: "",
+        searxngBaseUrl: "",
+        crawl4aiBaseUrl: "",
+        searchSvcBaseUrl: "",
+    };
+}

package/dist/runtime/context/context-compression-strategies.d.ts

@@ -0,0 +1,301 @@
+export interface CompressibleMessage {
+    role: string;
+    content?: string | unknown;
+    tool_call_id?: string;
+    tool_calls?: unknown;
+    name?: string;
+}
+export interface CompressionResult {
+    messages: CompressibleMessage[];
+    droppedCount: number;
+    strategy: string;
+    /** Phase 4: optional metrics from the compression pass */
+    metrics?: CompressionMetrics;
+}
+export interface CompressionMetrics {
+    tokensBefore: number;
+    tokensAfter: number;
+    compressionRatio: number;
+    /** ms elapsed for this strategy pass */
+    latencyMs: number;
+    /** Whether an LLM call was made during this pass */
+    usedLlm: boolean;
+    /** Whether prompt cache was invalidated by compression */
+    cacheInvalidated?: boolean;
+}
+export interface CompressionStrategy {
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+}
+/**
+ * Async compression strategy — required for LLM-based summarization.
+ * Falls back to sync `compress` when the caller doesn't support async.
+ */
+export interface AsyncCompressionStrategy extends CompressionStrategy {
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export declare function isAsyncCompressionStrategy(s: CompressionStrategy): s is AsyncCompressionStrategy;
+/** Caller-provided LLM summarization function (wired by Hub). */
+export type SummarizeFn = (messages: CompressibleMessage[], instruction: string) => Promise<string>;
+export declare class SlidingWindowStrategy implements CompressionStrategy {
+    private estimateTokens;
+    constructor(estimateTokens: (msg: CompressibleMessage) => number);
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+}
+export declare class SummarizeOldStrategy implements CompressionStrategy {
+    private recentCount;
+    private summarize;
+    constructor(recentCount: number, summarize: (messages: CompressibleMessage[]) => string);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+export declare class ToolResultTrimStrategy implements CompressionStrategy {
+    private maxToolResultChars;
+    constructor(maxToolResultChars?: number);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+export declare function composeStrategies(...strategies: CompressionStrategy[]): CompressionStrategy;
+/**
+ * Compose strategies with async support — if any strategy is async,
+ * the pipeline becomes async.
+ */
+export declare function composeAsyncStrategies(...strategies: CompressionStrategy[]): AsyncCompressionStrategy;
+/**
+ * Build the structured 9-section summary instruction for the LLM.
+ * Based on Claude Code's Full Compact mode, adapted for Hub.
+ */
+export declare function buildStructuredSummaryPrompt(messagesToSummarize: CompressibleMessage[], opts?: {
+    taskContext?: string;
+}): string;
+export interface HeadTailProtectionConfig {
+    /** Number of initial user-assistant exchanges to protect (default: 1) */
+    protectedHeadExchanges: number;
+    /** Number of recent messages to always keep (default: 8 = ~4 exchanges) */
+    protectedTailMessages: number;
+    /** The summarization callback */
+    summarize: SummarizeFn;
+    /** Optional token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+    /** Optional extra context for the summary prompt */
+    taskContext?: string;
+}
+/**
+ * Phase 2.2: Head/Tail protected summarization.
+ *
+ * Protects: system messages + first exchange + last N messages.
+ * Compresses: middle section via LLM summarization.
+ */
+export declare class HeadTailProtectedStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: HeadTailProtectionConfig);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface IncrementalCompactConfig {
+    /** Messages newer than this count are never summarized (default: 12) */
+    preserveRecentCount: number;
+    /** Summarization callback */
+    summarize: SummarizeFn;
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+}
+/**
+ * Phase 2.3: Incremental (partial) compaction.
+ *
+ * Only summarizes the oldest messages beyond the preserve window.
+ * Avoids repeatedly re-summarizing already-compressed content.
+ * If a previous summary marker exists, only new old messages are compressed.
+ */
+export declare class IncrementalCompactStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: IncrementalCompactConfig);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface CacheAwareCompressionConfig {
+    /** The inner strategy to delegate to */
+    inner: CompressionStrategy;
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number;
+    /**
+     * Callback: notify when prompt cache was invalidated by compression.
+     * Hub uses this to set pendingPostCompaction and track cache miss rate.
+     */
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}
+/**
+ * Phase 3: Cache-aware wrapper.
+ *
+ * Wraps any strategy and tracks whether compression invalidated the
+ * provider prompt cache. System prompt prefix stability is preserved
+ * by never modifying system[0] (the original system prompt).
+ */
+export declare class CacheAwareCompressionStrategy implements AsyncCompressionStrategy {
+    private config;
+    constructor(config: CacheAwareCompressionConfig);
+    compress(messages: CompressibleMessage[], budget: number): CompressionResult;
+    compressAsync(messages: CompressibleMessage[], budget: number): Promise<CompressionResult>;
+}
+export interface AdaptiveBudgetConfig {
+    /** Model context window size in tokens */
+    modelContextWindow: number;
+    /** Target usage ratio (0.0–1.0, default 0.75) — trigger compaction at this fraction */
+    targetUsageRatio: number;
+    /** Minimum guaranteed budget in tokens */
+    minBudget: number;
+    /** Maximum budget (usually = modelContextWindow) */
+    maxBudget: number;
+}
+export declare const DEFAULT_ADAPTIVE_BUDGET_CONFIG: AdaptiveBudgetConfig;
+/**
+ * Compute the adaptive token budget for a given model + message history.
+ *
+ * Adjusts based on model context window, and uses the target ratio
+ * so compression triggers before hitting the hard limit.
+ */
+export declare function computeAdaptiveBudget(config?: Partial<AdaptiveBudgetConfig>): number;
+/**
+ * Decide which compression tier to use based on current token count vs budget.
+ */
+export type CompressionTier = "none" | "trim-only" | "sliding-window" | "llm-summarize";
+export declare function selectCompressionTier(currentTokens: number, budget: number): CompressionTier;
+export interface CompressionEvent {
+    timestamp: number;
+    strategy: string;
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedCount: number;
+    latencyMs: number;
+    usedLlm: boolean;
+    cacheInvalidated: boolean;
+    tier: CompressionTier;
+}
+export interface CompressionMetricsSnapshot {
+    totalCompressions: number;
+    totalLlmCalls: number;
+    totalCacheInvalidations: number;
+    averageCompressionRatio: number;
+    averageLatencyMs: number;
+    totalTokensSaved: number;
+    recentEvents: CompressionEvent[];
+}
+export declare class CompressionMetricsCollector {
+    private events;
+    private maxEvents;
+    constructor(maxEvents?: number);
+    record(event: CompressionEvent): void;
+    snapshot(): CompressionMetricsSnapshot;
+    reset(): void;
+}
+/**
+ * A pluggable context engine. Only one can be active at a time.
+ * The default engine uses the 4-layer compression funnel.
+ */
+export interface ContextEngine {
+    /** Unique engine identifier */
+    readonly id: string;
+    /** Human-readable label */
+    readonly label: string;
+    /** Compress messages for a turn */
+    compressAsync(messages: CompressibleMessage[], budget: number, context?: {
+        model?: string;
+        sessionId?: string;
+    }): Promise<CompressionResult>;
+}
+/**
+ * Registry for context engines. Enforces single-active constraint.
+ */
+export declare class ContextEngineRegistry {
+    private engines;
+    private activeId;
+    register(engine: ContextEngine): void;
+    activate(id: string): boolean;
+    getActive(): ContextEngine | undefined;
+    listEngines(): Array<{
+        id: string;
+        label: string;
+        active: boolean;
+    }>;
+}
+/**
+ * MicroCompact — selective clearing of old compactable tool results.
+ *
+ * CC parity: microCompact.ts
+ *
+ * For tool result messages from COMPACTABLE_TOOLS, if the message is
+ * "old enough" (not in the most recent N messages), replace its content
+ * with a compact "[result cleared]" marker. This preserves the tool call
+ * structure (so the LLM knows what was called) but reclaims token budget.
+ *
+ * This is a lighter alternative to full summarization — it runs BEFORE
+ * LLM summarization as a first-pass reduction.
+ */
+export declare class MicroCompactStrategy implements CompressionStrategy {
+    /** Number of recent messages to preserve (don't clear) */
+    private preserveRecentCount;
+    /** Token estimator */
+    private estimateTokens;
+    constructor(
+    /** Number of recent messages to preserve (don't clear) */
+    preserveRecentCount?: number, 
+    /** Token estimator */
+    estimateTokens?: (msg: CompressibleMessage) => number);
+    compress(messages: CompressibleMessage[], _budget: number): CompressionResult;
+}
+/**
+ * After compaction, the most recently read/edited files may have been
+ * dropped from the conversation. CC re-injects up to N file contents
+ * to ensure the agent doesn't lose awareness of files it was working with.
+ *
+ * CC parity: compact.ts postCompactFileStateRecovery
+ */
+export interface PostCompactRecoveryConfig {
+    /** Maximum number of files to re-inject (default 5) */
+    maxFiles: number;
+    /** Maximum total tokens for re-injected files (default 50000) */
+    maxTokenBudget: number;
+    /** Function to read a file from disk (injected by caller) */
+    readFile: (path: string) => Promise<string | null>;
+    /** Token estimator */
+    estimateTokens?: (text: string) => number;
+}
+/**
+ * Extract file paths that were recently read/edited from the conversation.
+ * Looks at tool calls and results for file path arguments.
+ */
+export declare function extractRecentFilePaths(messages: CompressibleMessage[]): string[];
+/**
+ * Re-inject recently-used file contents after compaction.
+ *
+ * Call this AFTER compression but BEFORE sending to the LLM.
+ * Appends file content as system messages at the end of the
+ * system message block.
+ */
+export declare function postCompactFileRecovery(compressedMessages: CompressibleMessage[], originalMessages: CompressibleMessage[], config: PostCompactRecoveryConfig): Promise<CompressibleMessage[]>;
+/**
+ * Snip Compact — permanently remove specific messages by identifier.
+ *
+ * CC parity: services/compact/snipCompact.ts
+ *
+ * Unlike sliding window or summarization, snip removes messages by
+ * their unique id (tool_call_id, or index-based). This is used for:
+ * - Removing old tool results that are known to be stale
+ * - Dropping large image/media messages after they've been processed
+ * - Clearing tombstoned messages from the transcript
+ *
+ * Snip runs BEFORE microcompact and autocompact — both may fire
+ * after snip if the result is still over threshold.
+ */
+export interface SnipResult {
+    messages: CompressibleMessage[];
+    tokensFreed: number;
+    removedCount: number;
+    /** Optional boundary message to yield (marks snip point in transcript). */
+    boundaryMessage?: CompressibleMessage;
+}
+/**
+ * Remove messages whose tool_call_id or name matches the removedIds set.
+ * If no removedIds are pending, this is a no-op.
+ */
+export declare function snipCompactIfNeeded(messages: CompressibleMessage[], removedIds: Set<string>, estimateTokens?: (msg: CompressibleMessage) => number): SnipResult;