@psiclawops/hypermem 0.8.5 → 0.9.1

package/dist/repair-tool-pairs.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"repair-tool-pairs.d.ts","sourceRoot":"","sources":["../src/repair-tool-pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CA0LpE"}

package/dist/repair-tool-pairs.js

@@ -1,209 +0,0 @@
-/**
- * repair-tool-pairs.ts
- *
- * Strips orphaned tool result entries from a pi-agent message array.
- *
- * Background: HyperMem compaction and in-memory trim passes can remove assistant
- * messages that contain tool_use/toolCall blocks without removing the corresponding
- * tool result messages that follow them. Anthropic and Gemini reject these orphaned
- * tool results with a 400 error.
- *
- * This module provides a pure repair function that can be applied at any output
- * boundary to sanitise the message list before it reaches the provider.
- *
- * Supported formats:
- *   - pi-agent: role:'toolResult' messages with toolCallId field
- *   - Anthropic native: user messages with content blocks of type:'tool_result' and tool_use_id
- *
- * Returns a new array. Does not mutate the input.
- */
-/**
- * Repair orphaned tool pairs in a pi-agent / OpenClaw message array.
- *
- * Orphan types handled:
- *   1. role:'toolResult' message whose toolCallId has no matching toolCall/tool_use
- *      block in any assistant message in the array.
- *   2. User message whose content contains only type:'tool_result' blocks where all
- *      of those blocks reference a tool_use_id that does not appear in any assistant
- *      message in the array. (Anthropic-native format.)
- *
- * Also strips orphaned assistant messages that contain ONLY tool_use/toolCall blocks
- * where none of those calls has a corresponding tool result anywhere in the array.
- *
- * Returns a new array (does not mutate input).
- */
-export function repairToolPairs(messages) {
-    if (!Array.isArray(messages) || messages.length === 0)
-        return messages;
-    // ── Pass 1: Collect all valid tool call IDs from assistant messages ────────
-    const validCallIds = new Set();
-    for (const msg of messages) {
-        if (msg.role !== 'assistant')
-            continue;
-        // NeutralMessage format: msg.toolCalls[]
-        if (Array.isArray(msg.toolCalls)) {
-            for (const tc of msg.toolCalls) {
-                if (typeof tc.id === 'string' && tc.id)
-                    validCallIds.add(tc.id);
-            }
-        }
-        // Content array format: type:'toolCall' or type:'tool_use' blocks
-        if (Array.isArray(msg.content)) {
-            for (const block of msg.content) {
-                if ((block.type === 'toolCall' || block.type === 'tool_use') &&
-                    typeof block.id === 'string' &&
-                    block.id) {
-                    validCallIds.add(block.id);
-                }
-            }
-        }
-    }
-    // ── Pass 2: Collect all result IDs that have a valid call ─────────────────
-    const validResultIds = new Set();
-    for (const msg of messages) {
-        // pi-agent ToolResultMessage
-        if (msg.role === 'toolResult') {
-            const id = typeof msg.toolCallId === 'string' ? msg.toolCallId :
-                typeof msg.tool_call_id === 'string' ? msg.tool_call_id : '';
-            if (id && validCallIds.has(id))
-                validResultIds.add(id);
-        }
-        // Anthropic-native tool_result blocks inside user messages
-        if (msg.role === 'user' && Array.isArray(msg.content)) {
-            for (const block of msg.content) {
-                if (block.type === 'tool_result' && typeof block.tool_use_id === 'string' && block.tool_use_id) {
-                    if (validCallIds.has(block.tool_use_id))
-                        validResultIds.add(block.tool_use_id);
-                }
-            }
-        }
-    }
-    // ── Pass 3: Filter out orphaned messages / blocks ─────────────────────────
-    const result = [];
-    for (const msg of messages) {
-        // ── pi-agent ToolResultMessage ─────────────────────────────────────────
-        if (msg.role === 'toolResult') {
-            const id = typeof msg.toolCallId === 'string' ? msg.toolCallId :
-                typeof msg.tool_call_id === 'string' ? msg.tool_call_id : '';
-            if (!id || !validCallIds.has(id)) {
-                // Orphaned — drop
-                continue;
-            }
-            result.push(msg);
-            continue;
-        }
-        // ── Anthropic-native: user message with tool_result content blocks ─────
-        if (msg.role === 'user' && Array.isArray(msg.content)) {
-            const content = msg.content;
-            const hasToolResultBlocks = content.some(b => b.type === 'tool_result');
-            if (hasToolResultBlocks) {
-                const filteredContent = content.filter(block => {
-                    if (block.type !== 'tool_result')
-                        return true; // keep non-tool_result blocks
-                    const toolUseId = typeof block.tool_use_id === 'string' ? block.tool_use_id : '';
-                    return toolUseId && validCallIds.has(toolUseId);
-                });
-                // If the message became empty after stripping all orphaned tool_result blocks, skip it
-                if (filteredContent.length === 0)
-                    continue;
-                result.push({ ...msg, content: filteredContent });
-                continue;
-            }
-        }
-        // ── Assistant message with ONLY unmatched tool_use/toolCall blocks ─────
-        if (msg.role === 'assistant' && Array.isArray(msg.content)) {
-            const content = msg.content;
-            const toolCallBlocks = content.filter(b => b.type === 'toolCall' || b.type === 'tool_use');
-            const nonToolCallBlocks = content.filter(b => b.type !== 'toolCall' && b.type !== 'tool_use');
-            // Only strip if the assistant message is purely tool-calls (no text)
-            if (toolCallBlocks.length > 0 && nonToolCallBlocks.length === 0) {
-                const hasAnyResult = toolCallBlocks.some(b => {
-                    const id = typeof b.id === 'string' ? b.id : '';
-                    return id && validResultIds.has(id);
-                });
-                if (!hasAnyResult) {
-                    // Pure tool-call block with no paired results — drop
-                    continue;
-                }
-            }
-        }
-        result.push(msg);
-    }
-    // ── Pass 4: Intra-message content block integrity ─────────────────────────
-    // Anthropic requires that every tool_result content block in a user message
-    // references a tool_use_id that exists in the IMMEDIATELY PRECEDING assistant
-    // message's content blocks. Pass 3 only checks global existence. This pass
-    // enforces adjacency.
-    let intraBlockDropped = 0;
-    for (let i = 0; i < result.length; i++) {
-        const msg = result[i];
-        if (msg.role !== 'user' || !Array.isArray(msg.content))
-            continue;
-        const content = msg.content;
-        const hasToolResultBlocks = content.some(b => b.type === 'tool_result');
-        if (!hasToolResultBlocks)
-            continue;
-        // Find the immediately preceding assistant message
-        let precedingAssistant = null;
-        for (let j = i - 1; j >= 0; j--) {
-            if (result[j].role === 'assistant') {
-                precedingAssistant = result[j];
-                break;
-            }
-        }
-        // Collect tool_use IDs from the preceding assistant message only
-        const adjacentCallIds = new Set();
-        if (precedingAssistant) {
-            // Content array format
-            if (Array.isArray(precedingAssistant.content)) {
-                for (const block of precedingAssistant.content) {
-                    if ((block.type === 'toolCall' || block.type === 'tool_use') &&
-                        typeof block.id === 'string' && block.id) {
-                        adjacentCallIds.add(block.id);
-                    }
-                }
-            }
-            // NeutralMessage format
-            if (Array.isArray(precedingAssistant.toolCalls)) {
-                for (const tc of precedingAssistant.toolCalls) {
-                    if (typeof tc.id === 'string' && tc.id)
-                        adjacentCallIds.add(tc.id);
-                }
-            }
-        }
-        // Also check pi-agent ToolResultMessages that reference the preceding assistant
-        // (these are message-level, not content-block level — skip for adjacency check)
-        // Filter: keep tool_result blocks only if their tool_use_id is in the
-        // immediately preceding assistant message
-        const filteredContent = content.filter(block => {
-            if (block.type !== 'tool_result')
-                return true;
-            const toolUseId = typeof block.tool_use_id === 'string' ? block.tool_use_id : '';
-            if (!toolUseId)
-                return false; // malformed, drop
-            if (adjacentCallIds.has(toolUseId))
-                return true;
-            intraBlockDropped++;
-            return false;
-        });
-        if (filteredContent.length === 0) {
-            // All content blocks were orphaned — remove the message entirely
-            result.splice(i, 1);
-            i--; // re-check this index
-        }
-        else if (filteredContent.length !== content.length) {
-            result[i] = { ...msg, content: filteredContent };
-        }
-    }
-    const dropped = messages.length - result.length;
-    if (dropped > 0 || intraBlockDropped > 0) {
-        const parts = [];
-        if (dropped > 0)
-            parts.push(`${dropped} orphaned message(s)`);
-        if (intraBlockDropped > 0)
-            parts.push(`${intraBlockDropped} intra-message orphaned content block(s)`);
-        console.log(`[hypermem] repairToolPairs: dropped ${parts.join(' + ')} (${messages.length} → ${result.length})`);
-    }
-    return result;
-}
-//# sourceMappingURL=repair-tool-pairs.js.map

package/dist/replay-recovery.d.ts

@@ -1,29 +0,0 @@
-import { type ReplayMarker, type ReplayState } from './degradation.js';
-export interface ReplayRecoveryInputs {
-    currentState?: ReplayState | '' | null;
-    runtimeTokens: number;
-    redisTokens: number;
-    effectiveBudget: number;
-}
-export interface ReplayRecoveryDecision {
-    active: boolean;
-    shouldSkipCacheReplay: boolean;
-    trimTargetOverride?: number;
-    historyDepthCap?: number;
-    emittedMarker?: ReplayMarker;
-    emittedText?: string;
-    nextState: ReplayState | null;
-}
-export declare const REPLAY_RECOVERY_POLICY: {
-    readonly enterPressure: 0.8;
-    readonly exitPressure: 0.65;
-    readonly redisColdFraction: 0.2;
-    readonly enterTrimTarget: 0.2;
-    readonly stabilizingTrimTarget: 0.35;
-    readonly historyDepthCap: 60;
-    readonly redisFloorTokens: 500;
-};
-export declare function isColdRedisReplay(inputs: ReplayRecoveryInputs): boolean;
-export declare function isReplayRecovered(inputs: ReplayRecoveryInputs): boolean;
-export declare function decideReplayRecovery(inputs: ReplayRecoveryInputs): ReplayRecoveryDecision;
-//# sourceMappingURL=replay-recovery.d.ts.map

package/dist/replay-recovery.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"replay-recovery.d.ts","sourceRoot":"","sources":["../src/replay-recovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,WAAW,EACjB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,WAAW,GAAG,EAAE,GAAG,IAAI,CAAC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;CAC/B;AAED,eAAO,MAAM,sBAAsB;;;;;;;;CAQzB,CAAC;AAgBX,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAKvE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAKvE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CA+DzF"}

package/dist/replay-recovery.js

@@ -1,82 +0,0 @@
-import { formatReplayMarker, } from './degradation.js';
-export const REPLAY_RECOVERY_POLICY = {
-    enterPressure: 0.80,
-    exitPressure: 0.65,
-    redisColdFraction: 0.20,
-    enterTrimTarget: 0.20,
-    stabilizingTrimTarget: 0.35,
-    historyDepthCap: 60,
-    redisFloorTokens: 500,
-};
-function coldRedisThreshold(runtimeTokens) {
-    return Math.max(REPLAY_RECOVERY_POLICY.redisFloorTokens, Math.floor(runtimeTokens * REPLAY_RECOVERY_POLICY.redisColdFraction));
-}
-function recoveredRedisThreshold(effectiveBudget) {
-    return Math.max(REPLAY_RECOVERY_POLICY.redisFloorTokens, Math.floor(effectiveBudget * REPLAY_RECOVERY_POLICY.redisColdFraction));
-}
-export function isColdRedisReplay(inputs) {
-    return (inputs.runtimeTokens > inputs.effectiveBudget * REPLAY_RECOVERY_POLICY.enterPressure &&
-        inputs.redisTokens < coldRedisThreshold(inputs.runtimeTokens));
-}
-export function isReplayRecovered(inputs) {
-    return (inputs.runtimeTokens <= inputs.effectiveBudget * REPLAY_RECOVERY_POLICY.exitPressure &&
-        inputs.redisTokens >= recoveredRedisThreshold(inputs.effectiveBudget));
-}
-export function decideReplayRecovery(inputs) {
-    const currentState = inputs.currentState ?? null;
-    if (!currentState) {
-        if (!isColdRedisReplay(inputs)) {
-            return {
-                active: false,
-                shouldSkipCacheReplay: false,
-                nextState: null,
-            };
-        }
-        const emittedMarker = {
-            state: 'entering',
-            status: 'bounded',
-            reason: 'replay_cold_redis',
-            summary: 'cold restart, keep the window bounded',
-        };
-        return {
-            active: true,
-            shouldSkipCacheReplay: true,
-            trimTargetOverride: REPLAY_RECOVERY_POLICY.enterTrimTarget,
-            historyDepthCap: REPLAY_RECOVERY_POLICY.historyDepthCap,
-            emittedMarker,
-            emittedText: formatReplayMarker(emittedMarker),
-            nextState: 'stabilizing',
-        };
-    }
-    if (isReplayRecovered(inputs)) {
-        const emittedMarker = {
-            state: 'exited',
-            status: 'bounded',
-            reason: 'replay_exited',
-            summary: 'stable window restored',
-        };
-        return {
-            active: false,
-            shouldSkipCacheReplay: false,
-            emittedMarker,
-            emittedText: formatReplayMarker(emittedMarker),
-            nextState: null,
-        };
-    }
-    const emittedMarker = {
-        state: 'stabilizing',
-        status: 'bounded',
-        reason: 'replay_stabilizing',
-        summary: 'replay window stabilizing, keep it bounded',
-    };
-    return {
-        active: true,
-        shouldSkipCacheReplay: true,
-        trimTargetOverride: REPLAY_RECOVERY_POLICY.stabilizingTrimTarget,
-        historyDepthCap: REPLAY_RECOVERY_POLICY.historyDepthCap,
-        emittedMarker,
-        emittedText: formatReplayMarker(emittedMarker),
-        nextState: 'stabilizing',
-    };
-}
-//# sourceMappingURL=replay-recovery.js.map

package/dist/reranker.d.ts

@@ -1,95 +0,0 @@
-/**
- * hypermem Reranker
- *
- * Pluggable reranking interface with circuit-breaker protection and graceful
- * degradation. Callers that receive null fall back to the original document
- * order without disruption.
- *
- * Providers:
- *   - ZeroEntropyReranker — https://api.zeroentropy.dev/v1/rerank (zerank-2)
- *   - OpenRouterReranker  — https://openrouter.ai/api/v1/rerank (cohere/rerank-4-pro)
- *   - OllamaReranker      — http://localhost:11434/api/chat (yes/no classification)
- *
- * API key resolution order (per provider):
- *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
- *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
- */
-export interface RerankResult {
-    index: number;
-    score: number;
-    content: string;
-}
-export interface RerankerProvider {
-    readonly name: string;
-    /**
-     * Reranks `documents` by relevance to `query`.
-     * Returns null on any failure — callers MUST fall back to original order.
-     */
-    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
-}
-export interface RerankerConfig {
-    provider: 'zeroentropy' | 'openrouter' | 'local' | 'none';
-    minCandidates: number;
-    maxDocuments: number;
-    topK: number;
-    timeoutMs: number;
-    zeroEntropyApiKey?: string;
-    zeroEntropyModel?: string;
-    openrouterApiKey?: string;
-    openrouterModel?: string;
-    ollamaUrl?: string;
-    ollamaModel?: string;
-}
-export declare class ZeroEntropyReranker implements RerankerProvider {
-    readonly name = "zeroentropy";
-    private readonly circuit;
-    private readonly apiKey;
-    private readonly model;
-    private readonly timeoutMs;
-    constructor(apiKey: string, model?: string, timeoutMs?: number);
-    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
-}
-export declare class OpenRouterReranker implements RerankerProvider {
-    readonly name = "openrouter";
-    private readonly circuit;
-    private readonly apiKey;
-    private readonly model;
-    private readonly timeoutMs;
-    constructor(apiKey: string, model?: string, timeoutMs?: number);
-    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
-}
-export declare class OllamaReranker implements RerankerProvider {
-    readonly name = "ollama";
-    private readonly circuit;
-    private readonly baseUrl;
-    private readonly model;
-    private readonly timeoutMs;
-    constructor(baseUrl?: string, model?: string, timeoutMs?: number);
-    /**
-     * Scores documents sequentially — one chat call per document.
-     * The Qwen3-Reranker-0.6B model responds with "yes" (relevant) or "no".
-     * Score: yes → 1.0, anything else → 0.0.
-     *
-     * Sequential iteration is required because Ollama's /api/chat is stateless
-     * per-request and running calls in parallel would overload a local GPU.
-     * Returns null on the first failure to preserve circuit breaker semantics.
-     */
-    rerank(query: string, documents: string[], topK?: number): Promise<RerankResult[] | null>;
-}
-/**
- * Creates a RerankerProvider from the supplied config.
- *
- * API key resolution order:
- *   zeroentropy: config.zeroEntropyApiKey → ZEROENTROPY_API_KEY env var
- *   openrouter:  config.openrouterApiKey  → OPENROUTER_API_KEY env var
- *
- * Returns null when:
- *   - provider is 'none'
- *   - provider is 'zeroentropy' and no key found in config or env
- *   - provider is 'openrouter' and no key found in config or env
- *
- * 'local' (Ollama) never returns null from the factory — it has no required
- * API key. The provider itself returns null on runtime failure.
- */
-export declare function createReranker(config: RerankerConfig): RerankerProvider | null;
-//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../src/reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAgFH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,aAAa,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC1D,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,qBAAa,mBAAoB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,KAAK,SAAa,EAAE,SAAS,SAAO;IAM1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CAqC5F;AAID,qBAAa,kBAAmB,YAAW,gBAAgB;IACzD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwB,EAAE,SAAS,SAAO;IAMrE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CAqC5F;AAQD,qBAAa,cAAe,YAAW,gBAAgB;IACrD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAGjC,OAAO,SAA2B,EAClC,KAAK,SAAuC,EAC5C,SAAS,SAAS;IAOpB;;;;;;;;OAQG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,IAAI,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;CA4C5F;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,GAAG,IAAI,CAyB9E"}