qlogicagent 2.13.4 → 2.13.5

package/dist/runtime/execution/tool-result-storage.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool result storage — CC toolResultStorage.ts aligned.
+ *
+ * Two-layer mechanism to manage tool result sizes:
+ *   Level 1 (per-tool): At execution time, results > DEFAULT_MAX_RESULT_SIZE_CHARS
+ *           are persisted to disk and replaced with preview references.
+ *   Level 2 (per-message budget): Before API call, aggregate tool results in
+ *           each group (consecutive tool messages between assistant messages)
+ *           are checked against MAX_TOOL_RESULTS_PER_MESSAGE_CHARS. The largest
+ *           fresh results are persisted until under budget.
+ *
+ * ContentReplacementState tracks decisions across turns for prompt cache
+ * stability — once a tool result's fate is decided (replaced or not), the
+ * decision is frozen for the remainder of the conversation.
+ *
+ * CC reference: src/utils/toolResultStorage.ts
+ * Zero imports from express/pg/ioredis/ws.
+ */
+export declare const TOOL_RESULTS_SUBDIR = "tool-results";
+/** XML tag wrapping persisted output previews (CC PERSISTED_OUTPUT_TAG) */
+export declare const PERSISTED_OUTPUT_TAG = "<persisted-output>";
+export declare const PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>";
+/** Marker injected by microcompact when clearing old tool results (CC parity) */
+export declare const TOOL_RESULT_CLEARED_MESSAGE = "[Old tool result content cleared]";
+/**
+ * Per-conversation-thread state for the aggregate tool result budget.
+ * State must be stable to preserve prompt cache:
+ *   - seenIds: tool_call_ids that have passed through the budget check (replaced
+ *     or not). Once seen, a result's fate is frozen for the conversation.
+ *   - replacements: subset of seenIds that were persisted to disk and
+ *     replaced with previews, mapped to the exact preview string.
+ *     Re-application is a Map lookup — no file I/O, byte-identical.
+ *
+ * CC reference: ContentReplacementState
+ */
+export type ContentReplacementState = {
+    seenIds: Set<string>;
+    replacements: Map<string, string>;
+};
+export type PersistedToolResult = {
+    filepath: string;
+    originalSize: number;
+    preview: string;
+    hasMore: boolean;
+};
+export declare function createContentReplacementState(): ContentReplacementState;
+export declare function generatePreview(content: string, maxBytes: number): {
+    preview: string;
+    hasMore: boolean;
+};
+export declare function persistToolResult(content: string, toolCallId: string, sessionId: string): Promise<PersistedToolResult | null>;
+/**
+ * Build a reference message for large tool results (CC buildLargeToolResultMessage parity).
+ */
+export declare function buildLargeToolResultMessage(result: PersistedToolResult): string;
+/**
+ * If content exceeds threshold, persist to disk and return a preview reference.
+ * Falls back to hard truncation if persistence fails.
+ * Called at tool execution time in streaming-tool-executor.ts.
+ */
+export declare function maybePersistLargeToolResult(content: string, toolCallId: string, sessionId: string, threshold?: number): Promise<string>;
+interface MessageLike {
+    role: string;
+    content?: string | unknown;
+    tool_call_id?: string;
+}
+/**
+ * Enforce per-message aggregate budget on tool results.
+ * CC enforceToolResultBudget parity.
+ *
+ * For each group of tool messages whose content together exceeds
+ * the per-message limit, the largest FRESH (never-before-seen) results
+ * are persisted to disk and replaced with previews.
+ *
+ * State is tracked by tool_call_id: once a result is seen, its fate is
+ * frozen. Previously-replaced results get the same replacement re-applied
+ * (no I/O, byte-identical). Previously-unreplaced results are never
+ * replaced later (would break prompt cache).
+ *
+ * @param state — MUTATED in place (seenIds and replacements updated)
+ * @returns messages with replacements applied + count of new replacements
+ */
+export declare function enforceToolResultBudget(messages: MessageLike[], state: ContentReplacementState, sessionId: string, limit?: number): Promise<{
+    messages: MessageLike[];
+    newlyReplacedCount: number;
+}>;
+export {};

package/dist/runtime/execution/tool-result-storage.js

@@ -0,0 +1,274 @@
+/**
+ * Tool result storage — CC toolResultStorage.ts aligned.
+ *
+ * Two-layer mechanism to manage tool result sizes:
+ *   Level 1 (per-tool): At execution time, results > DEFAULT_MAX_RESULT_SIZE_CHARS
+ *           are persisted to disk and replaced with preview references.
+ *   Level 2 (per-message budget): Before API call, aggregate tool results in
+ *           each group (consecutive tool messages between assistant messages)
+ *           are checked against MAX_TOOL_RESULTS_PER_MESSAGE_CHARS. The largest
+ *           fresh results are persisted until under budget.
+ *
+ * ContentReplacementState tracks decisions across turns for prompt cache
+ * stability — once a tool result's fate is decided (replaced or not), the
+ * decision is frozen for the remainder of the conversation.
+ *
+ * CC reference: src/utils/toolResultStorage.ts
+ * Zero imports from express/pg/ioredis/ws.
+ */
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+import { DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_TOOL_RESULTS_PER_MESSAGE_CHARS, TOOL_RESULT_PREVIEW_BYTES, } from "../config/tunable-defaults.js";
+// ── Constants / Tags (CC parity) ─────────────────────────────────────────────
+export const TOOL_RESULTS_SUBDIR = "tool-results";
+/** XML tag wrapping persisted output previews (CC PERSISTED_OUTPUT_TAG) */
+export const PERSISTED_OUTPUT_TAG = "<persisted-output>";
+export const PERSISTED_OUTPUT_CLOSING_TAG = "</persisted-output>";
+/** Marker injected by microcompact when clearing old tool results (CC parity) */
+export const TOOL_RESULT_CLEARED_MESSAGE = "[Old tool result content cleared]";
+// ── State management ─────────────────────────────────────────────────────────
+export function createContentReplacementState() {
+    return { seenIds: new Set(), replacements: new Map() };
+}
+// ── Session directory ────────────────────────────────────────────────────────
+function getToolResultsDir(sessionId) {
+    return join(tmpdir(), "qlogicagent-sessions", sessionId, TOOL_RESULTS_SUBDIR);
+}
+async function ensureToolResultsDir(sessionId) {
+    try {
+        await mkdir(getToolResultsDir(sessionId), { recursive: true });
+    }
+    catch {
+        // Directory may already exist
+    }
+}
+function getToolResultPath(sessionId, id) {
+    // Sanitize id to prevent path traversal
+    const safeId = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return join(getToolResultsDir(sessionId), `${safeId}.txt`);
+}
+// ── Preview (CC generatePreview parity) ──────────────────────────────────────
+export function generatePreview(content, maxBytes) {
+    if (content.length <= maxBytes) {
+        return { preview: content, hasMore: false };
+    }
+    const truncated = content.slice(0, maxBytes);
+    const lastNewline = truncated.lastIndexOf("\n");
+    const cutPoint = lastNewline > maxBytes * 0.5 ? lastNewline : maxBytes;
+    return { preview: content.slice(0, cutPoint), hasMore: true };
+}
+// ── Detection ────────────────────────────────────────────────────────────────
+function isContentAlreadyCompacted(content) {
+    return content.includes(PERSISTED_OUTPUT_TAG);
+}
+// ── Persistence (CC persistToolResult parity) ────────────────────────────────
+export async function persistToolResult(content, toolCallId, sessionId) {
+    await ensureToolResultsDir(sessionId);
+    const filepath = getToolResultPath(sessionId, toolCallId);
+    try {
+        // 'wx' flag: exclusive create — skip if file already exists (idempotent).
+        // CC uses the same pattern to prevent re-writing on replayed turns.
+        await writeFile(filepath, content, { encoding: "utf-8", flag: "wx" });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "EEXIST") {
+            return null; // Persistence failed; caller handles fallback
+        }
+        // EEXIST: already persisted on a prior turn — fall through to preview
+    }
+    const { preview, hasMore } = generatePreview(content, TOOL_RESULT_PREVIEW_BYTES);
+    return { filepath, originalSize: content.length, preview, hasMore };
+}
+/**
+ * Build a reference message for large tool results (CC buildLargeToolResultMessage parity).
+ */
+export function buildLargeToolResultMessage(result) {
+    let message = `${PERSISTED_OUTPUT_TAG}\n`;
+    message += `Output too large (${result.originalSize} chars). Full output saved to: ${result.filepath}\n\n`;
+    message += `Preview (first ${TOOL_RESULT_PREVIEW_BYTES} bytes):\n`;
+    message += result.preview;
+    message += result.hasMore ? "\n...\n" : "\n";
+    message += PERSISTED_OUTPUT_CLOSING_TAG;
+    return message;
+}
+// ── Level 1: Per-tool persistence (CC maybePersistLargeToolResult parity) ────
+/**
+ * If content exceeds threshold, persist to disk and return a preview reference.
+ * Falls back to hard truncation if persistence fails.
+ * Called at tool execution time in streaming-tool-executor.ts.
+ */
+export async function maybePersistLargeToolResult(content, toolCallId, sessionId, threshold = DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    if (content.length <= threshold)
+        return content;
+    if (isContentAlreadyCompacted(content))
+        return content;
+    const result = await persistToolResult(content, toolCallId, sessionId);
+    if (result) {
+        return buildLargeToolResultMessage(result);
+    }
+    // Persistence failed — fall back to hard truncation
+    return content.slice(0, threshold) + `\n...[truncated ${content.length - threshold} chars]`;
+}
+/**
+ * Group tool messages by "response batch" — all consecutive tool messages
+ * between assistant messages form one group. Mirrors CC's collectCandidatesByMessage
+ * adapted for OpenAI-format (standalone role:"tool" messages vs Anthropic blocks).
+ *
+ * CC groups by wire-level user messages (Anthropic merges consecutive user messages);
+ * our equivalent is consecutive tool messages between assistant boundaries.
+ */
+function collectCandidatesByGroup(messages) {
+    const groups = [];
+    let current = [];
+    for (const msg of messages) {
+        if (msg.role === "tool" && typeof msg.content === "string" && msg.tool_call_id) {
+            if (!isContentAlreadyCompacted(msg.content)) {
+                current.push({
+                    toolCallId: msg.tool_call_id,
+                    content: msg.content,
+                    size: msg.content.length,
+                });
+            }
+        }
+        else if (msg.role === "assistant") {
+            if (current.length > 0) {
+                groups.push(current);
+                current = [];
+            }
+        }
+        // system/user messages don't create group boundaries (CC parity:
+        // only assistant messages create wire-level boundaries)
+    }
+    if (current.length > 0) {
+        groups.push(current);
+    }
+    return groups;
+}
+/**
+ * Partition candidates by prior decision state (CC partitionByPriorDecision parity):
+ *   - mustReapply: previously replaced → re-apply cached replacement (byte-identical)
+ *   - frozen: previously seen, left unreplaced → off-limits (changing would break cache)
+ *   - fresh: never seen → eligible for new replacement decisions
+ */
+function partitionByPriorDecision(candidates, state) {
+    const mustReapply = [];
+    const frozen = [];
+    const fresh = [];
+    for (const c of candidates) {
+        const replacement = state.replacements.get(c.toolCallId);
+        if (replacement !== undefined) {
+            mustReapply.push({ ...c, replacement });
+        }
+        else if (state.seenIds.has(c.toolCallId)) {
+            frozen.push(c);
+        }
+        else {
+            fresh.push(c);
+        }
+    }
+    return { mustReapply, frozen, fresh };
+}
+/**
+ * Select the largest fresh results to persist until under budget (CC selectFreshToReplace parity).
+ * If frozen results alone exceed budget, accept the overage — microcompact will clear them.
+ */
+function selectFreshToReplace(fresh, frozenSize, limit) {
+    const sorted = [...fresh].sort((a, b) => b.size - a.size);
+    const selected = [];
+    let remaining = frozenSize + fresh.reduce((sum, c) => sum + c.size, 0);
+    for (const c of sorted) {
+        if (remaining <= limit)
+            break;
+        selected.push(c);
+        remaining -= c.size;
+    }
+    return selected;
+}
+/**
+ * Enforce per-message aggregate budget on tool results.
+ * CC enforceToolResultBudget parity.
+ *
+ * For each group of tool messages whose content together exceeds
+ * the per-message limit, the largest FRESH (never-before-seen) results
+ * are persisted to disk and replaced with previews.
+ *
+ * State is tracked by tool_call_id: once a result is seen, its fate is
+ * frozen. Previously-replaced results get the same replacement re-applied
+ * (no I/O, byte-identical). Previously-unreplaced results are never
+ * replaced later (would break prompt cache).
+ *
+ * @param state — MUTATED in place (seenIds and replacements updated)
+ * @returns messages with replacements applied + count of new replacements
+ */
+export async function enforceToolResultBudget(messages, state, sessionId, limit = MAX_TOOL_RESULTS_PER_MESSAGE_CHARS) {
+    const groups = collectCandidatesByGroup(messages);
+    if (groups.length === 0) {
+        return { messages, newlyReplacedCount: 0 };
+    }
+    const replacementMap = new Map();
+    const toPersist = [];
+    for (const candidates of groups) {
+        const { mustReapply, frozen, fresh } = partitionByPriorDecision(candidates, state);
+        // Re-apply cached replacements (no I/O, byte-identical — CC parity)
+        for (const c of mustReapply) {
+            replacementMap.set(c.toolCallId, c.replacement);
+        }
+        if (fresh.length === 0) {
+            // All candidates already seen — just ensure seenIds updated
+            for (const c of candidates)
+                state.seenIds.add(c.toolCallId);
+            continue;
+        }
+        const frozenSize = frozen.reduce((sum, c) => sum + c.size, 0);
+        const freshSize = fresh.reduce((sum, c) => sum + c.size, 0);
+        const selected = frozenSize + freshSize > limit
+            ? selectFreshToReplace(fresh, frozenSize, limit)
+            : [];
+        // Mark non-selected as seen NOW (synchronously, before async persist).
+        // CC invariant: selectedIds are marked AFTER persist+replacements.set
+        // to keep the pair atomic (no concurrent reader sees X∈seenIds but X∉replacements).
+        const selectedIds = new Set(selected.map((c) => c.toolCallId));
+        for (const c of candidates) {
+            if (!selectedIds.has(c.toolCallId)) {
+                state.seenIds.add(c.toolCallId);
+            }
+        }
+        if (selected.length > 0) {
+            toPersist.push(...selected);
+        }
+    }
+    if (replacementMap.size === 0 && toPersist.length === 0) {
+        return { messages, newlyReplacedCount: 0 };
+    }
+    // Persist fresh selections concurrently (CC parity: Promise.all)
+    const freshResults = await Promise.all(toPersist.map(async (c) => {
+        const result = await persistToolResult(c.content, c.toolCallId, sessionId);
+        return { candidate: c, result };
+    }));
+    let newlyReplacedCount = 0;
+    for (const { candidate, result } of freshResults) {
+        // Mark seen post-await, atomically with replacements.set (CC invariant)
+        state.seenIds.add(candidate.toolCallId);
+        if (!result)
+            continue; // Persistence failed — treat as frozen
+        const replacement = buildLargeToolResultMessage(result);
+        replacementMap.set(candidate.toolCallId, replacement);
+        state.replacements.set(candidate.toolCallId, replacement);
+        newlyReplacedCount++;
+    }
+    if (replacementMap.size === 0) {
+        return { messages, newlyReplacedCount: 0 };
+    }
+    // Apply replacements to messages (immutable — new array, original untouched)
+    const result = messages.map((msg) => {
+        if (msg.role !== "tool" || !msg.tool_call_id)
+            return msg;
+        const replacement = replacementMap.get(msg.tool_call_id);
+        if (replacement === undefined)
+            return msg;
+        return { ...msg, content: replacement };
+    });
+    return { messages: result, newlyReplacedCount };
+}

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

@@ -0,0 +1,61 @@
+import { ContextEngineRegistry, type CompressibleMessage, type CompressionResult, type CompressionStrategy, type AsyncCompressionStrategy, type SummarizeFn } from "../context/context-compression-strategies.js";
+import type { HookRegistry } from "./hook-registry.js";
+import type { RuntimeLogger } from "./hook-registry.js";
+import type { LLMTransport } from "../ports/index.js";
+/** Rough token estimate: ~4 chars per token for mixed CJK/English. */
+export declare function estimateTokens(msg: CompressibleMessage): number;
+/** Estimate total tokens for a message array. */
+export declare function estimateTotalTokens(messages: CompressibleMessage[]): number;
+export declare function getCompressionMetrics(): import("../context/context-compression-strategies.js").CompressionMetricsSnapshot;
+export declare function getContextEngineRegistry(): ContextEngineRegistry;
+/**
+ * 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 declare function createSummarizeFn(log: RuntimeLogger, opts?: {
+    transport?: LLMTransport;
+    apiKey?: string;
+    model?: string;
+}): SummarizeFn;
+/** Phase 1: sync-only pipeline (ToolResultTrim + MicroCompact + SlidingWindow) */
+export declare function createSyncPipeline(): CompressionStrategy;
+/** Phase 2+3: async pipeline with LLM summarization + cache awareness */
+export declare function createAsyncPipeline(summarize: SummarizeFn, opts?: {
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}): AsyncCompressionStrategy;
+/** Phase 2.3: incremental compaction pipeline (for partial compact) */
+export declare function createIncrementalPipeline(summarize: SummarizeFn, opts?: {
+    preserveRecentCount?: number;
+    onCacheInvalidated?: (info: {
+        droppedCount: number;
+        strategy: string;
+    }) => void;
+}): AsyncCompressionStrategy;
+export interface CompressOptions {
+    budget?: number;
+    model?: string;
+    pipeline?: CompressionStrategy;
+    allowLlm?: boolean;
+    summarize?: SummarizeFn;
+    sessionId?: string;
+}
+/** Synchronous compression (Phase 1 only). */
+export declare function compressMessages(messages: CompressibleMessage[], opts?: CompressOptions): CompressionResult;
+/** Async compression (Phase 2+) — supports LLM summarization. */
+export declare function compressMessagesAsync(messages: CompressibleMessage[], opts: CompressOptions & {
+    summarize: SummarizeFn;
+}): Promise<CompressionResult>;
+export declare function registerDefaultContextEngine(log: RuntimeLogger, opts?: {
+    transport?: LLMTransport;
+    apiKey?: string;
+    model?: string;
+}): void;
+export declare function registerContextCompressionHook(hooks: HookRegistry, log: RuntimeLogger, opts?: {
+    transport?: LLMTransport;
+    apiKey?: string;
+    model?: string;
+}): void;