@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/profiles.js

@@ -0,0 +1,227 @@
+/**
+ * hypermem configuration profiles
+ *
+ * Pre-built configs for common deployment patterns. Pass to createHyperMem()
+ * directly or use as a base for custom configs via mergeProfile().
+ *
+ * Profiles:
+ *   minimal  — 64k context, single agent, low resource usage
+ *   standard — 128k context, fleet default, balanced
+ *   rich     — 200k+ context, multi-agent, full feature set
+ */
+// ---------------------------------------------------------------------------
+// Shared base (fields common across all profiles)
+// ---------------------------------------------------------------------------
+const BASE_CACHE = {
+    keyPrefix: 'hm:',
+    sessionTTL: 3600,
+    historyTTL: 86400,
+};
+const BASE_EMBEDDING = {
+    ollamaUrl: 'http://localhost:11434',
+    model: 'nomic-embed-text',
+    dimensions: 768,
+    timeout: 10000,
+    batchSize: 32,
+};
+// ---------------------------------------------------------------------------
+// light — 64k context window, single agent, constrained resources
+//
+// Design intent:
+//   - Small local models (Mistral 7B, Phi-3, Llama 3 8B) at 64k context
+//   - Single agent — no cross-session context needed
+//   - Minimal ACA stack — no dreaming, no background indexing overhead
+//   - Low Redis churn — longer flush intervals, shorter history window
+//   - outputProfile: 'light' — ~100 token standalone directives, no fleet concepts
+//   - No parallel operations — sequential fact extraction only
+// ---------------------------------------------------------------------------
+const LIGHT_COMPOSITOR = {
+    defaultTokenBudget: 40000, // leaves ~24k for model output at 64k window
+    maxHistoryMessages: 200, // keep window tight — small models lose coherence past ~150 msgs
+    maxFacts: 15, // surface top facts only, don't swamp the window
+    maxCrossSessionContext: 0, // single agent — no cross-session
+    maxRecentToolPairs: 2, // minimal tool history
+    maxProseToolPairs: 4,
+    warmHistoryBudgetFraction: 0.35, // slightly less history, more room for context
+    contextWindowReserve: 0.35, // generous reserve — small models need output headroom
+    dynamicReserveEnabled: true,
+    dynamicReserveTurnHorizon: 3, // shorter horizon — small sessions
+    dynamicReserveMax: 0.50,
+    keystoneHistoryFraction: 0.1, // light keystone — history window is already small
+    keystoneMaxMessages: 5,
+    keystoneMinSignificance: 0.7, // higher bar — only high-signal keystone messages
+    targetBudgetFraction: 0.50, // Anvil spec: 0.50 for light
+    maxTotalTriggerTokens: 1500, // tight trigger ceiling
+    outputProfile: 'light', // standalone density directives only, no fleet concepts
+    wikiTokenCap: 300, // Anvil spec: 300 for light
+};
+const LIGHT_INDEXER = {
+    enabled: true,
+    factExtractionMode: 'pattern', // pattern only — tiered extraction is heavier
+    topicDormantAfter: '12h', // faster dormancy — small systems don't need long windows
+    topicClosedAfter: '48h',
+    factDecayRate: 0.05, // slightly faster decay — fewer facts, keep them fresh
+    episodeSignificanceThreshold: 0.6, // higher bar — only store meaningful episodes
+    periodicInterval: 120000, // 2min — less frequent background work on small systems
+    batchSize: 64,
+    maxMessagesPerTick: 200,
+};
+export const lightProfile = {
+    enabled: true,
+    dataDir: './hypermem-data',
+    cache: BASE_CACHE,
+    compositor: LIGHT_COMPOSITOR,
+    indexer: LIGHT_INDEXER,
+    embedding: {
+        ...BASE_EMBEDDING,
+        batchSize: 8, // smaller batches — don't spike memory on embed
+        timeout: 15000, // more generous timeout — local hardware can be slow
+    },
+    // dreaming: disabled (default) — don't run background promotion on small systems
+    // obsidian: disabled (default)
+};
+// ---------------------------------------------------------------------------
+// standard — 128k context window, fleet default, balanced
+//
+// Design intent:
+//   - Mid-range models (Sonnet, GPT-5-mini, Gemini Flash) at 128k
+//   - Small multi-agent setups or single power-user agents
+//   - Full ACA stack — dreaming optional, background indexing on
+//   - outputProfile: 'standard' — full FOS, no MOD
+// ---------------------------------------------------------------------------
+const STANDARD_COMPOSITOR = {
+    defaultTokenBudget: 90000,
+    maxHistoryMessages: 500,
+    maxFacts: 30,
+    maxCrossSessionContext: 4000,
+    maxRecentToolPairs: 3,
+    maxProseToolPairs: 10,
+    warmHistoryBudgetFraction: 0.40,
+    contextWindowReserve: 0.25,
+    dynamicReserveEnabled: true,
+    dynamicReserveTurnHorizon: 5,
+    dynamicReserveMax: 0.50,
+    keystoneHistoryFraction: 0.20,
+    keystoneMaxMessages: 15,
+    keystoneMinSignificance: 0.5,
+    targetBudgetFraction: 0.65, // Anvil spec: 0.65 for standard
+    maxTotalTriggerTokens: 4000,
+    outputProfile: 'standard', // full FOS, MOD suppressed
+    wikiTokenCap: 600, // Anvil spec: 600 for standard
+};
+const STANDARD_INDEXER = {
+    enabled: true,
+    factExtractionMode: 'tiered',
+    topicDormantAfter: '24h',
+    topicClosedAfter: '72h',
+    factDecayRate: 0.02,
+    episodeSignificanceThreshold: 0.5,
+    periodicInterval: 60000, // 1min — standard background cadence
+    batchSize: 128,
+    maxMessagesPerTick: 500,
+};
+export const standardProfile = {
+    enabled: true,
+    dataDir: './hypermem-data',
+    cache: BASE_CACHE,
+    compositor: STANDARD_COMPOSITOR,
+    indexer: STANDARD_INDEXER,
+    embedding: BASE_EMBEDDING,
+};
+// ---------------------------------------------------------------------------
+// extended — 200k+ context window, multi-agent, full feature set
+//
+// Design intent:
+//   - Large context models (Opus, GPT-5.4, Gemini Pro) at 200k+
+//   - Council / multi-agent fleet deployments
+//   - Full ACA stack including dreaming, background indexing, cross-session
+//   - outputProfile: 'full' — FOS + MOD, full spec
+//   - Higher keystone threshold — more historical context worth surfacing
+// ---------------------------------------------------------------------------
+const EXTENDED_COMPOSITOR = {
+    defaultTokenBudget: 160000,
+    maxHistoryMessages: 1000,
+    maxFacts: 60,
+    maxCrossSessionContext: 12000,
+    maxRecentToolPairs: 5,
+    maxProseToolPairs: 15,
+    warmHistoryBudgetFraction: 0.45,
+    contextWindowReserve: 0.20,
+    dynamicReserveEnabled: true,
+    dynamicReserveTurnHorizon: 7,
+    dynamicReserveMax: 0.45,
+    keystoneHistoryFraction: 0.25,
+    keystoneMaxMessages: 30,
+    keystoneMinSignificance: 0.4,
+    targetBudgetFraction: 0.55, // Anvil spec: 0.55 for extended (history is huge, budget carefully)
+    maxTotalTriggerTokens: 10000,
+    outputProfile: 'full', // FOS + MOD — full fleet spec
+    wikiTokenCap: 800, // Anvil spec: 800 for extended
+};
+const EXTENDED_INDEXER = {
+    enabled: true,
+    factExtractionMode: 'tiered',
+    topicDormantAfter: '48h',
+    topicClosedAfter: '168h', // 7 days — long-running council topics stay warm
+    factDecayRate: 0.01, // slow decay — preserve more institutional memory
+    episodeSignificanceThreshold: 0.4,
+    periodicInterval: 30000, // 30s — frequent background work for fleet throughput
+    batchSize: 256,
+    maxMessagesPerTick: 1000,
+};
+export const fullProfile = {
+    enabled: true,
+    dataDir: './hypermem-data',
+    cache: BASE_CACHE,
+    compositor: EXTENDED_COMPOSITOR,
+    indexer: EXTENDED_INDEXER,
+    embedding: {
+        ...BASE_EMBEDDING,
+        batchSize: 64, // larger batches — more throughput for fleet ingest
+        timeout: 8000, // tighter timeout — expect capable hardware
+    },
+};
+// Legacy aliases — kept for backward compat, removed in 1.0
+export const minimalProfile = lightProfile;
+export const extendedProfile = fullProfile;
+export const richProfile = fullProfile;
+export const PROFILES = {
+    light: lightProfile,
+    standard: standardProfile,
+    full: fullProfile,
+};
+/**
+ * Load a named profile.
+ *
+ * @example
+ * const config = getProfile('light');
+ * const hm = createHyperMem(config);
+ */
+export function getProfile(name) {
+    // backward compat
+    if (name === 'extended')
+        return structuredClone(fullProfile);
+    return structuredClone(PROFILES[name]);
+}
+/**
+ * Merge a partial config on top of a named profile.
+ * Deep-merges compositor and indexer; top-level fields are replaced.
+ *
+ * @example
+ * const config = mergeProfile('light', {
+ *   cache: { keyPrefix: 'myapp:' },
+ *   compositor: { outputProfile: 'standard' },  // upgrade tier
+ * });
+ */
+export function mergeProfile(name, overrides) {
+    const base = getProfile(name);
+    return {
+        ...base,
+        ...overrides,
+        compositor: { ...base.compositor, ...(overrides.compositor ?? {}) },
+        indexer: { ...base.indexer, ...(overrides.indexer ?? {}) },
+        embedding: { ...base.embedding, ...(overrides.embedding ?? {}) },
+        cache: { ...base.cache, ...(overrides.cache ?? {}) },
+    };
+}
+//# sourceMappingURL=profiles.js.map

package/dist/provider-translator.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Provider Translator
+ * hypermem Provider Translator
  *
  * Converts between provider-neutral (NeutralMessage) and provider-specific formats.
  * This is the ONLY place where provider-specific formatting exists.
@@ -10,12 +10,22 @@
  */
 import type { NeutralMessage, NeutralToolResult, ProviderMessage } from './types.js';
 /**
- * Generate a HyperMem-native tool call ID.
+ * Final pair-integrity sweep before provider translation.
+ *
+ * Invariant: never emit a tool_result unless its matching tool_use/tool_call
+ * exists in the immediately prior assistant message with the same ID.
+ *
+ * If the pair is broken, degrade the orphan tool_result into plain user text
+ * so providers never see an invalid tool_result block.
+ */
+export declare function repairToolCallPairs(messages: NeutralMessage[]): NeutralMessage[];
+/**
+ * Generate a hypermem-native tool call ID.
  * These are provider-neutral and deterministic within a session.
  */
 export declare function generateToolCallId(): string;
 /**
- * Convert a provider-specific tool call ID to a HyperMem ID.
+ * Convert a provider-specific tool call ID to a hypermem ID.
  * Deterministic: same input always produces same output.
  */
 export declare function normalizeToolCallId(providerId: string): string;

package/dist/provider-translator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-translator.d.ts","sourceRoot":"","sources":["../src/provider-translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EAEd,iBAAiB,EACjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAOpB;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAK3C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI9D;AAID,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,kBAAkB,GAAG,SAAS,CAAC;AAEnF,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAOtF;AAgMD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,eAAe,EAAE,CAcnB;AA8ED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,MAAM,GACf,cAAc,CAYhB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAQxG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,cAAc,CAOjF"}
+{"version":3,"file":"provider-translator.d.ts","sourceRoot":"","sources":["../src/provider-translator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EAEd,iBAAiB,EACjB,eAAe,EAChB,MAAM,YAAY,CAAC;AAYpB;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CA4ChF;AAOD;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAK3C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI9D;AAID,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,kBAAkB,GAAG,SAAS,CAAC;AAEnF,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAOtF;AAgMD;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,eAAe,EAAE,CAenB;AA8ED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,QAAQ,EAAE,MAAM,GACf,cAAc,CAYhB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAQxG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,cAAc,CAOjF"}

package/dist/provider-translator.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Provider Translator
+ * hypermem Provider Translator
  *
  * Converts between provider-neutral (NeutralMessage) and provider-specific formats.
  * This is the ONLY place where provider-specific formatting exists.
@@ -8,11 +8,64 @@
  * This eliminates grafting/stripping entirely — tool calls are stored as structured
  * data, and each provider gets the format it expects at send time.
  */
+function summarizeOrphanToolResult(tr) {
+    const toolName = tr.name || 'tool';
+    const status = tr.isError ? 'error' : 'result';
+    const content = (tr.content || '').replace(/\s+/g, ' ').trim();
+    const preview = content.length > 160 ? `${content.slice(0, 157)}...` : content;
+    return preview
+        ? `[${toolName} ${status} omitted: missing matching tool call] ${preview}`
+        : `[${toolName} ${status} omitted: missing matching tool call]`;
+}
+/**
+ * Final pair-integrity sweep before provider translation.
+ *
+ * Invariant: never emit a tool_result unless its matching tool_use/tool_call
+ * exists in the immediately prior assistant message with the same ID.
+ *
+ * If the pair is broken, degrade the orphan tool_result into plain user text
+ * so providers never see an invalid tool_result block.
+ */
+export function repairToolCallPairs(messages) {
+    const repaired = [];
+    for (const msg of messages) {
+        if (msg.role !== 'user' || !msg.toolResults || msg.toolResults.length === 0) {
+            repaired.push(msg);
+            continue;
+        }
+        const prev = repaired[repaired.length - 1];
+        const validCallIds = new Set(prev?.role === 'assistant' && prev.toolCalls
+            ? prev.toolCalls.map(tc => tc.id)
+            : []);
+        const keptResults = msg.toolResults.filter(tr => validCallIds.has(tr.callId));
+        const orphanResults = msg.toolResults.filter(tr => !validCallIds.has(tr.callId));
+        if (orphanResults.length === 0) {
+            repaired.push(msg);
+            continue;
+        }
+        const orphanText = orphanResults.map(summarizeOrphanToolResult).join('\n');
+        const mergedText = [msg.textContent, orphanText].filter(Boolean).join('\n');
+        if (keptResults.length > 0) {
+            repaired.push({
+                ...msg,
+                textContent: mergedText || msg.textContent,
+                toolResults: keptResults,
+            });
+            continue;
+        }
+        repaired.push({
+            ...msg,
+            textContent: mergedText || msg.textContent || '[tool result omitted: missing matching tool call]',
+            toolResults: null,
+        });
+    }
+    return repaired;
+}
 import { createHash } from 'node:crypto';
 // ─── ID Generation ───────────────────────────────────────────────
 let idCounter = 0;
 /**
- * Generate a HyperMem-native tool call ID.
+ * Generate a hypermem-native tool call ID.
  * These are provider-neutral and deterministic within a session.
  */
 export function generateToolCallId() {
@@ -22,7 +75,7 @@ export function generateToolCallId() {
     return `hm_${timestamp}_${counter}`;
 }
 /**
- * Convert a provider-specific tool call ID to a HyperMem ID.
+ * Convert a provider-specific tool call ID to a hypermem ID.
  * Deterministic: same input always produces same output.
  */
 export function normalizeToolCallId(providerId) {
@@ -52,8 +105,8 @@ export function detectProvider(providerString) {
  * The last system message BEFORE the dynamicBoundary marker gets
  * cache_control: {type: "ephemeral"} to mark the static/dynamic boundary.
  *
- * Static (cacheable): system prompt + identity — stable across sessions
- * Dynamic (not cacheable): context block (facts/recall), conversation history
+ * Static (cacheable): system prompt + identity + stable output profile prefix
+ * Dynamic (not cacheable): context block (facts/recall/recent actions), conversation history
  *
  * This allows Anthropic to cache the static prefix and skip re-tokenizing it.
  */
@@ -225,17 +278,18 @@ function toOpenAIResponses(messages) {
  * Convert neutral messages to provider-specific format.
  */
 export function toProviderFormat(messages, provider) {
+    const repairedMessages = repairToolCallPairs(messages);
     const providerType = detectProvider(provider);
     switch (providerType) {
         case 'anthropic':
-            return toAnthropic(messages);
+            return toAnthropic(repairedMessages);
         case 'openai':
-            return toOpenAI(messages);
+            return toOpenAI(repairedMessages);
         case 'openai-responses':
-            return toOpenAIResponses(messages);
+            return toOpenAIResponses(repairedMessages);
         default:
             // Default to OpenAI format as it's most widely compatible
-            return toOpenAI(messages);
+            return toOpenAI(repairedMessages);
     }
 }
 // ─── From Provider Format ────────────────────────────────────────

package/dist/rate-limiter.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Rate Limiter
+ * hypermem Rate Limiter
  *
  * Token-bucket rate limiter for embedding API calls.
  * Prevents hammering Ollama during bulk indexing.

package/dist/rate-limiter.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Rate Limiter
+ * hypermem Rate Limiter
  *
  * Token-bucket rate limiter for embedding API calls.
  * Prevents hammering Ollama during bulk indexing.

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

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+type AnyMessage = Record<string, unknown>;
+/**
+ * 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 declare function repairToolPairs(messages: AnyMessage[]): AnyMessage[];
+export {};
+//# sourceMappingURL=repair-tool-pairs.d.ts.map

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

@@ -0,0 +1 @@
+{"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,CAmHpE"}

package/dist/repair-tool-pairs.js

@@ -0,0 +1,138 @@
+/**
+ * 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);
+    }
+    const dropped = messages.length - result.length;
+    if (dropped > 0) {
+        console.log(`[hypermem] repairToolPairs: dropped ${dropped} orphaned message(s) (${messages.length} → ${result.length})`);
+    }
+    return result;
+}
+//# sourceMappingURL=repair-tool-pairs.js.map

package/dist/retrieval-policy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * hypermem Retrieval Policy
+ *
+ * Single enforced policy layer for scope-based access control during retrieval.
+ * Called by the compositor to filter items before they are injected into context.
+ *
+ * Scope rules:
+ *   'agent' (default / null / undefined): allowed if agentId matches OR is null/undefined (global)
+ *   'session': allowed if both agentId AND sessionKey match
+ *   'user': allowed if agentId matches
+ *   'global': always allowed
+ *   any other value: denied with reason 'ambiguous_scope'
+ */
+export type RetrievalScope = 'agent' | 'session' | 'user' | 'global';
+export interface RetrievalContext {
+    agentId: string;
+    sessionKey: string;
+}
+export interface ScopeCheckResult {
+    allowed: boolean;
+    /** One of: 'allowed' | 'scope_filtered' | 'ambiguous_scope' */
+    reason: string;
+}
+/**
+ * Check whether a single item is accessible in the given retrieval context.
+ *
+ * @param itemScope       The scope stored on the item (null/undefined → defaults to 'agent')
+ * @param itemAgentId     The agentId stored on the item (null/undefined → global)
+ * @param itemSessionKey  The sessionKey stored on the item (null/undefined → any)
+ * @param ctx             The requester's retrieval context
+ */
+export declare function checkScope(itemScope: string | null | undefined, itemAgentId: string | null | undefined, itemSessionKey: string | null | undefined, ctx: RetrievalContext): ScopeCheckResult;
+/**
+ * Filter an array of items by scope, returning allowed items and a filtered count.
+ *
+ * Items are expected to have optional `agentId`, `sessionKey`, and `scope` fields.
+ * Null/undefined fields are treated as "unset" (permissive for their slot).
+ *
+ * @param items  Array of items to filter
+ * @param ctx    The requester's retrieval context
+ * @returns      { allowed: T[], filteredCount: number }
+ */
+export declare function filterByScope<T extends {
+    agentId?: string | null;
+    sessionKey?: string | null;
+    scope?: string | null;
+}>(items: T[], ctx: RetrievalContext): {
+    allowed: T[];
+    filteredCount: number;
+};
+//# sourceMappingURL=retrieval-policy.d.ts.map

package/dist/retrieval-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-policy.d.ts","sourceRoot":"","sources":["../src/retrieval-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACpC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACzC,GAAG,EAAE,gBAAgB,GACpB,gBAAgB,CAqClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IACtC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,EACC,KAAK,EAAE,CAAC,EAAE,EACV,GAAG,EAAE,gBAAgB,GACpB;IAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAczC"}