qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/hooks/context-compression.js

@@ -0,0 +1,334 @@
+// ============================================================
+// Context Compression Bridge — wires orchestration compression
+// strategies into the Agent turn execution flow.
+//
+// Ported from src/core/runtime/context-compression-bridge.ts.
+// Key change: createSummarizeFn() accepts injected LLM transport
+// instead of hardcoding admin proxy URL. Falls back to sync summary
+// when no LLM is available (CLI standalone mode).
+//
+// Phase 1 (P0): ToolResultTrim + SlidingWindow (no LLM needed)
+// Phase 2 (P1): LLM Summarization — HeadTail + Incremental
+// Phase 3 (P1): Prompt Cache awareness
+// Phase 4 (P2): Adaptive threshold + metrics + engine plugin
+// ============================================================
+import { composeStrategies, composeAsyncStrategies, SlidingWindowStrategy, ToolResultTrimStrategy, HeadTailProtectedStrategy, IncrementalCompactStrategy, CacheAwareCompressionStrategy, CompressionMetricsCollector, ContextEngineRegistry, MicroCompactStrategy, postCompactFileRecovery, computeAdaptiveBudget, selectCompressionTier, isAsyncCompressionStrategy, } from "../context/context-compression-strategies.js";
+import { readFile as fsReadFile } from "node:fs/promises";
+import { getModelRegistry } from "../infra/model-registry.js";
+// ── Token estimation ───────────────────────────────────────
+/** Rough token estimate: ~4 chars per token for mixed CJK/English. */
+export function estimateTokens(msg) {
+    const text = typeof msg.content === "string"
+        ? msg.content
+        : msg.content != null
+            ? JSON.stringify(msg.content)
+            : "";
+    return Math.ceil(text.length / 4);
+}
+/** Estimate total tokens for a message array. */
+export function estimateTotalTokens(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        total += estimateTokens(msg);
+    }
+    return total;
+}
+// ── Model context window lookup ────────────────────────────
+const MODEL_CONTEXT_WINDOWS = {
+    "deepseek-v4-flash": 1_000_000,
+    "deepseek-v4-pro": 1_000_000,
+    "deepseek-chat": 1_000_000,
+    "deepseek-reasoner": 1_000_000,
+    "gpt-4o": 128_000,
+    "gpt-4o-mini": 128_000,
+    "claude-sonnet-4-20250514": 200_000,
+    "claude-3-5-haiku-20241022": 200_000,
+    "gemini-3.1-pro-preview": 1_000_000,
+    "gemini-3-flash-preview": 1_000_000,
+    "gemini-3.1-flash-lite": 1_000_000,
+};
+function getModelContextWindow(model) {
+    if (!model)
+        return 128_000;
+    if (model in MODEL_CONTEXT_WINDOWS)
+        return MODEL_CONTEXT_WINDOWS[model];
+    const lower = model.toLowerCase();
+    for (const [key, value] of Object.entries(MODEL_CONTEXT_WINDOWS)) {
+        if (lower.startsWith(key.toLowerCase()))
+            return value;
+    }
+    return 128_000;
+}
+// ── Constants ──────────────────────────────────────────────
+const DEFAULT_TOOL_RESULT_MAX_CHARS = 8_000;
+/** Compression uses mainLoopModel (CC parity: compactConversation uses mainLoopModel, never degrades). */
+const SUMMARIZE_MODEL_FALLBACK = "deepseek-v4-flash";
+function getSummarizeModel() {
+    return getModelRegistry().resolveModelForPurpose("textGeneration") ?? SUMMARIZE_MODEL_FALLBACK;
+}
+// ── Singleton metrics collector (Phase 4) ──────────────────
+const metricsCollector = new CompressionMetricsCollector(200);
+export function getCompressionMetrics() {
+    return metricsCollector.snapshot();
+}
+// ── Singleton context engine registry (Phase 4.3) ──────────
+const engineRegistry = new ContextEngineRegistry();
+export function getContextEngineRegistry() {
+    return engineRegistry;
+}
+// ── LLM Summarization Callback Factory ─────────────────────
+/**
+ * Create a summarization callback using an injected LLM transport.
+ * For CLI mode: uses the same transport that powers the agent loop.
+ * Falls back to non-LLM summary when transport/apiKey not available.
+ */
+export function createSummarizeFn(log, opts) {
+    return async (messages, instruction) => {
+        const transport = opts?.transport;
+        const apiKey = opts?.apiKey;
+        if (!transport || !apiKey) {
+            log.debug("[context-compression] no LLM transport for summarization — using sync fallback");
+            return fallbackSyncSummary(messages);
+        }
+        try {
+            let content = "";
+            const model = opts?.model ?? getSummarizeModel();
+            for await (const chunk of transport.stream({
+                model,
+                messages: [
+                    { role: "system", content: "You are a precise conversation summarizer." },
+                    { role: "user", content: instruction },
+                ],
+                maxTokens: 2000,
+                temperature: 0.3,
+            }, apiKey, AbortSignal.timeout(30_000))) {
+                if (chunk.type === "delta")
+                    content += chunk.text;
+            }
+            if (!content) {
+                log.warn("[context-compression] empty summary response");
+                return fallbackSyncSummary(messages);
+            }
+            return content;
+        }
+        catch (err) {
+            log.warn({ err: err.message }, "[context-compression] summarize call error — using fallback");
+            return fallbackSyncSummary(messages);
+        }
+    };
+}
+/** Non-LLM fallback: extract user messages + assistant key responses as bullet points. */
+function fallbackSyncSummary(messages) {
+    const parts = [];
+    // Extract ALL user messages (critical for recall)
+    const userMsgs = messages.filter((m) => m.role === "user");
+    const userBullets = userMsgs.slice(0, 20).map((m) => {
+        const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? "");
+        return `- [user]: ${text.slice(0, 300)}${text.length > 300 ? "..." : ""}`;
+    });
+    parts.push(`## User Requests (${userMsgs.length} messages)`);
+    parts.push(...userBullets);
+    // Extract assistant message summaries (first 100 chars each)
+    const assistantMsgs = messages.filter((m) => m.role === "assistant");
+    if (assistantMsgs.length > 0) {
+        const assistantBullets = assistantMsgs.slice(0, 10).map((m) => {
+            const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content ?? "");
+            return `- [assistant]: ${text.slice(0, 150)}${text.length > 150 ? "..." : ""}`;
+        });
+        parts.push("", `## Assistant Responses (${assistantMsgs.length} total)`);
+        parts.push(...assistantBullets);
+    }
+    return parts.join("\n");
+}
+// ── Pipeline factories ─────────────────────────────────────
+/** Phase 1: sync-only pipeline (ToolResultTrim + MicroCompact + SlidingWindow) */
+export function createSyncPipeline() {
+    return composeStrategies(new ToolResultTrimStrategy(DEFAULT_TOOL_RESULT_MAX_CHARS), new MicroCompactStrategy(20, estimateTokens), new SlidingWindowStrategy(estimateTokens));
+}
+/** Phase 2+3: async pipeline with LLM summarization + cache awareness */
+export function createAsyncPipeline(summarize, opts) {
+    const innerPipeline = composeAsyncStrategies(new ToolResultTrimStrategy(DEFAULT_TOOL_RESULT_MAX_CHARS), new MicroCompactStrategy(20, estimateTokens), new HeadTailProtectedStrategy({
+        protectedHeadExchanges: 1,
+        protectedTailMessages: 8,
+        summarize,
+        estimateTokens,
+    }), new SlidingWindowStrategy(estimateTokens));
+    return new CacheAwareCompressionStrategy({
+        inner: innerPipeline,
+        estimateTokens,
+        onCacheInvalidated: opts?.onCacheInvalidated,
+    });
+}
+/** Phase 2.3: incremental compaction pipeline (for partial compact) */
+export function createIncrementalPipeline(summarize, opts) {
+    const innerPipeline = composeAsyncStrategies(new ToolResultTrimStrategy(DEFAULT_TOOL_RESULT_MAX_CHARS), new IncrementalCompactStrategy({
+        preserveRecentCount: opts?.preserveRecentCount ?? 12,
+        summarize,
+        estimateTokens,
+    }), new SlidingWindowStrategy(estimateTokens));
+    return new CacheAwareCompressionStrategy({
+        inner: innerPipeline,
+        estimateTokens,
+        onCacheInvalidated: opts?.onCacheInvalidated,
+    });
+}
+// ── Post-compact hook callback ─────────────────────────────
+/** Module-level callback set by registerContextCompressionHook to fire context.after_compact. */
+let onAfterCompact = null;
+/** Synchronous compression (Phase 1 only). */
+export function compressMessages(messages, opts) {
+    const budget = opts?.budget ?? computeAdaptiveBudget({
+        modelContextWindow: getModelContextWindow(opts?.model),
+    });
+    const pipeline = opts?.pipeline ?? createSyncPipeline();
+    const result = pipeline.compress(messages, budget);
+    if (result.droppedCount > 0) {
+        const tokensBefore = estimateTotalTokens(messages);
+        const tokensAfter = estimateTotalTokens(result.messages);
+        metricsCollector.record({
+            timestamp: Date.now(),
+            strategy: result.strategy,
+            tokensBefore,
+            tokensAfter,
+            droppedCount: result.droppedCount,
+            latencyMs: result.metrics?.latencyMs ?? 0,
+            usedLlm: false,
+            cacheInvalidated: result.metrics?.cacheInvalidated ?? false,
+            tier: selectCompressionTier(tokensBefore, budget),
+        });
+    }
+    if (result.droppedCount > 0) {
+        onAfterCompact?.(result.droppedCount, estimateTotalTokens(result.messages));
+    }
+    return result;
+}
+/** Async compression (Phase 2+) — supports LLM summarization. */
+export async function compressMessagesAsync(messages, opts) {
+    const budget = opts.budget ?? computeAdaptiveBudget({
+        modelContextWindow: getModelContextWindow(opts.model),
+    });
+    const activeEngine = engineRegistry.getActive();
+    if (activeEngine) {
+        const result = await activeEngine.compressAsync(messages, budget, {
+            model: opts.model,
+            sessionId: opts.sessionId,
+        });
+        recordMetrics(messages, result, budget);
+        return result;
+    }
+    return compressWithTierSelection(messages, opts, budget);
+}
+async function compressWithTierSelection(messages, opts, budget) {
+    const effectiveBudget = budget ?? computeAdaptiveBudget({
+        modelContextWindow: getModelContextWindow(opts.model),
+    });
+    const currentTokens = estimateTotalTokens(messages);
+    const tier = selectCompressionTier(currentTokens, effectiveBudget);
+    let result;
+    switch (tier) {
+        case "none":
+            result = { messages, droppedCount: 0, strategy: "none" };
+            break;
+        case "trim-only":
+            result = new ToolResultTrimStrategy(DEFAULT_TOOL_RESULT_MAX_CHARS).compress(messages, effectiveBudget);
+            break;
+        case "sliding-window": {
+            const swPipeline = createAsyncPipeline(opts.summarize);
+            result = await swPipeline.compressAsync(messages, effectiveBudget);
+            break;
+        }
+        case "llm-summarize": {
+            const pipeline = opts.pipeline ?? createAsyncPipeline(opts.summarize);
+            result = isAsyncCompressionStrategy(pipeline)
+                ? await pipeline.compressAsync(messages, effectiveBudget)
+                : pipeline.compress(messages, effectiveBudget);
+            break;
+        }
+    }
+    // Post-compact file recovery: re-inject file content dropped during compression
+    if (result.droppedCount > 0) {
+        result = {
+            ...result,
+            messages: await postCompactFileRecovery(result.messages, messages, {
+                maxFiles: 5,
+                maxTokenBudget: 50_000,
+                readFile: async (path) => {
+                    try {
+                        return await fsReadFile(path, "utf-8");
+                    }
+                    catch {
+                        return null;
+                    }
+                },
+            }),
+        };
+    }
+    recordMetrics(messages, result, effectiveBudget);
+    return result;
+}
+function recordMetrics(messagesBefore, result, budget) {
+    if (result.droppedCount > 0 || result.metrics?.usedLlm) {
+        const tokensBefore = result.metrics?.tokensBefore || estimateTotalTokens(messagesBefore);
+        const tokensAfter = result.metrics?.tokensAfter || estimateTotalTokens(result.messages);
+        metricsCollector.record({
+            timestamp: Date.now(),
+            strategy: result.strategy,
+            tokensBefore,
+            tokensAfter,
+            droppedCount: result.droppedCount,
+            latencyMs: result.metrics?.latencyMs ?? 0,
+            usedLlm: result.metrics?.usedLlm ?? false,
+            cacheInvalidated: result.metrics?.cacheInvalidated ?? false,
+            tier: selectCompressionTier(tokensBefore, budget),
+        });
+    }
+    if (result.droppedCount > 0) {
+        const afterTokens = result.metrics?.tokensAfter || estimateTotalTokens(result.messages);
+        onAfterCompact?.(result.droppedCount, afterTokens);
+    }
+}
+// ── Default Context Engine (Phase 4.3) ─────────────────────
+export function registerDefaultContextEngine(log, opts) {
+    const summarize = createSummarizeFn(log, opts);
+    const engine = {
+        id: "builtin-compressor",
+        label: "4-Layer Compression Funnel (built-in)",
+        async compressAsync(messages, budget, context) {
+            return compressWithTierSelection(messages, {
+                budget,
+                model: context?.model,
+                sessionId: context?.sessionId,
+                summarize,
+            }, budget);
+        },
+    };
+    engineRegistry.register(engine);
+    engineRegistry.activate(engine.id);
+    log.info(`[context-compression] registered context engine: ${engine.id}`);
+}
+// ── Hook registration ──────────────────────────────────────
+export function registerContextCompressionHook(hooks, log, opts) {
+    registerDefaultContextEngine(log, opts);
+    hooks.register({
+        point: "context.before_compact",
+        priority: 50,
+        label: "context-compression-bridge",
+        handler: (_point, context) => {
+            const messageCount = context.messageCount;
+            if (messageCount && messageCount > 0) {
+                log.debug(`[context-compression] before_compact: ${messageCount} messages entering compression`);
+            }
+            return { action: "continue" };
+        },
+    });
+    // Wire context.after_compact via module-level callback
+    onAfterCompact = (removedCount, tokenCount) => {
+        log.debug(`[context-compression] after_compact: removed ${removedCount}, ${tokenCount} tokens remaining`);
+        hooks.invoke("context.after_compact", {
+            sessionId: "",
+            turnId: "",
+            removedCount,
+            tokenCount,
+        }).catch(() => { });
+    };
+}

package/dist/runtime/hooks/hook-registry.d.ts

@@ -0,0 +1,12 @@
+import type { HookPoint, HookContextMap, HookResult, HookHandler, HookRegistration, HookRegistry } from "../../contracts/hooks.js";
+export type { HookPoint, HookContextMap, HookResult, HookHandler, HookRegistration, HookRegistry };
+/** Minimal logger interface — compatible with both pino and AgentLogger. */
+export interface RuntimeLogger {
+    info(msg: string): void;
+    info(obj: Record<string, unknown>, msg: string): void;
+    warn(msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+    debug(msg: string): void;
+    debug(obj: Record<string, unknown>, msg: string): void;
+}
+export declare function createHookRegistry(log: RuntimeLogger): HookRegistry;

package/dist/runtime/hooks/hook-registry.js

@@ -0,0 +1,61 @@
+// ============================================================
+// Hook registry — manages lifecycle hooks for the Agent Runtime.
+// Hook failures never block the main flow (catch + log).
+//
+// Ported from src/core/runtime/hook-registry.ts (zero changes to logic).
+// ============================================================
+export function createHookRegistry(log) {
+    const handlers = new Map();
+    return {
+        register(registration) {
+            const list = handlers.get(registration.point) ?? [];
+            const entry = {
+                handler: registration.handler,
+                priority: registration.priority ?? 100,
+                label: registration.label,
+                critical: registration.critical,
+            };
+            list.push(entry);
+            list.sort((a, b) => a.priority - b.priority);
+            handlers.set(registration.point, list);
+            return () => {
+                const idx = list.indexOf(entry);
+                if (idx >= 0)
+                    list.splice(idx, 1);
+            };
+        },
+        async invoke(point, context) {
+            const list = handlers.get(point);
+            if (!list || list.length === 0) {
+                return { action: "continue", context };
+            }
+            let current = context;
+            for (const entry of list) {
+                try {
+                    const result = await entry.handler(point, current);
+                    if (!result || result.action === "continue") {
+                        if (result?.context) {
+                            current = result.context;
+                        }
+                        continue;
+                    }
+                    if (result.action === "abort" || result.action === "skip") {
+                        log.info({ hook: point, label: entry.label, action: result.action, reason: result.reason }, "hook intercepted");
+                        return result;
+                    }
+                }
+                catch (err) {
+                    if (entry.critical) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        const label = entry.label ?? point;
+                        const reason = `critical hook ${label} failed: ${message}`;
+                        log.warn({ hook: point, label: entry.label, err: message }, "critical hook handler failed (blocking)");
+                        return { action: "abort", reason };
+                    }
+                    log.warn({ hook: point, label: entry.label, err: err.message }, "hook handler failed (non-blocking)");
+                }
+            }
+            return { action: "continue", context: current };
+        },
+    };
+}

package/dist/runtime/hooks/hook-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/hooks/hook-registry.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from "vitest";
+import { createHookRegistry } from "./hook-registry.js";
+function testLogger() {
+    return {
+        info: vi.fn(),
+        warn: vi.fn(),
+        debug: vi.fn(),
+    };
+}
+describe("createHookRegistry", () => {
+    it("continues when a non-critical hook throws", async () => {
+        const hooks = createHookRegistry(testLogger());
+        hooks.register({
+            point: "tool.before_invoke",
+            label: "observer",
+            handler: () => {
+                throw new Error("observer failed");
+            },
+        });
+        const result = await hooks.invoke("tool.before_invoke", {
+            sessionId: "s1",
+            turnId: "t1",
+            callId: "c1",
+            toolName: "read",
+            arguments: {},
+        });
+        expect(result.action).toBe("continue");
+    });
+    it("aborts when a critical preflight hook throws", async () => {
+        const hooks = createHookRegistry(testLogger());
+        hooks.register({
+            point: "tool.before_invoke",
+            label: "permission-checker",
+            critical: true,
+            handler: () => {
+                throw new Error("permission unavailable");
+            },
+        });
+        const result = await hooks.invoke("tool.before_invoke", {
+            sessionId: "s1",
+            turnId: "t1",
+            callId: "c1",
+            toolName: "write",
+            arguments: {},
+        });
+        expect(result).toMatchObject({
+            action: "abort",
+            reason: "critical hook permission-checker failed: permission unavailable",
+        });
+    });
+});

package/dist/runtime/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { createHookRegistry, type RuntimeLogger } from "./hook-registry.js";
+export { registerMemoryHooks, createMemoryPrefetchState, type MemoryHooksDeps, type MemoryPrefetchState, MEMORY_PREFETCH_CONFIG, } from "./memory-hooks.js";
+export { registerContextCompressionHook, compressMessages } from "./context-compression.js";
+export { registerSkillRecallHooks, detectRetrospectiveTrigger, invalidateSkillRecallCache, type SkillRecallHooksDeps, SKILL_RECALL_CONFIG, } from "./skill-recall-hooks.js";

package/dist/runtime/hooks/index.js

@@ -0,0 +1,5 @@
+// runtime/hooks — hook infrastructure subsystem
+export { createHookRegistry } from "./hook-registry.js";
+export { registerMemoryHooks, createMemoryPrefetchState, MEMORY_PREFETCH_CONFIG, } from "./memory-hooks.js";
+export { registerContextCompressionHook, compressMessages } from "./context-compression.js";
+export { registerSkillRecallHooks, detectRetrospectiveTrigger, invalidateSkillRecallCache, SKILL_RECALL_CONFIG, } from "./skill-recall-hooks.js";

package/dist/runtime/hooks/memory-hooks.d.ts

@@ -0,0 +1,75 @@
+import type { HookRegistry } from "../../contracts/hooks.js";
+import type { MemoryProvider } from "../ports/memory-provider.js";
+import type { MemoryWriter } from "../ports/memory-writer.js";
+import type { MemoryRecallSource } from "../ports/memory-recall-source.js";
+export declare const MEMORY_PREFETCH_CONFIG: {
+    readonly MAX_SESSION_BYTES: number;
+    readonly LIMIT_PER_RECALL: 10;
+    readonly MAX_SURFACED_ENTRIES: 100;
+};
+export interface MemoryHooksDeps {
+    /** QMemory adapter (MemoryProvider with search/health). */
+    memoryProvider?: MemoryProvider;
+    /** Local memory provider for direct writes (auto-extract). */
+    localMemoryProvider?: MemoryWriter;
+    /** User ID for memory lookups. */
+    userId: string;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+    /** Access to recent messages (for auto-extract). Set externally per turn. */
+    getLastUserMessage?: () => string | undefined;
+    /** Access to last assistant response (for implicit extraction). Set externally per turn. */
+    getLastAssistantMessage?: () => string | undefined;
+    /** Background LLM for implicit extraction. If provided, enables Layer 2. */
+    llmExtract?: (prompt: string) => Promise<string | null>;
+}
+/** Session-scoped state for dedup and byte budget (CC parity). */
+export interface MemoryPrefetchState {
+    /** Paths already surfaced this session (CC readFileState LRU parity). */
+    surfacedPaths: Set<string>;
+    /** Total bytes injected this session. */
+    sessionBytes: number;
+}
+/**
+ * Create a fresh memory prefetch state (once per session).
+ */
+export declare function createMemoryPrefetchState(): MemoryPrefetchState;
+/**
+ * Register memory lifecycle hooks on the HookRegistry.
+ *
+ * Hook points wired:
+ *   - memory.before_recall: prefetch context from qmemory (query-based)
+ *   - memory.after_recall: log recall results
+ *
+ * CC parity additions:
+ *   - LRU dedup via surfacedPaths (filterDuplicateMemoryAttachments)
+ *   - Session byte limit (MAX_SESSION_BYTES = 60KB)
+ *   - Async prefetch (non-blocking promise, abort-aware)
+ *
+ * Returns a cleanup function to unregister.
+ */
+export declare function registerMemoryHooks(hooks: HookRegistry, deps: MemoryHooksDeps, 
+/** Shared statepass the same object across hook re-registrations in a session. */
+prefetchState?: MemoryPrefetchState): () => void;
+export interface MemdirRecallHookDeps {
+    /** Project memory recall source (lazy: may be null at registration time). */
+    getMemorySource: () => MemoryRecallSource | null;
+    /** Logger. */
+    log: {
+        debug(msg: string): void;
+        warn(msg: string): void;
+    };
+}
+/**
+ * Register the MEMDIR cross-file recall hook on `memory.before_recall`.
+ *
+ * - Priority 40 (before QMemory at 50)
+ * - Scans topic files, selects top-5 relevant
+ * - Injects content into recalledMemories (merged with QMemory results)
+ * - Respects session byte budget from shared MemoryPrefetchState
+ * - Dedup via surfacedPaths (shared with QMemory hook)
+ */
+export declare function registerMemdirRecallHook(hooks: HookRegistry, deps: MemdirRecallHookDeps, prefetchState?: MemoryPrefetchState): () => void;