@aexol/spectral 0.9.15 → 0.9.17

package/dist/memory/compaction.d.ts

@@ -1,7 +1,7 @@
 import { agentLoop } from "../sdk/agent-core/index.js";
 import { type Model } from "../sdk/ai/index.js";
 import type { MemoryReflection, ObservationRecord } from "./types.js";
-export declare const REFLECTOR_MAX_PASSES = 2;
+export declare const REFLECTOR_MAX_PASSES = 1;
 export declare const PRUNER_MAX_PASSES = 2;
 export declare function observationPoolTokens(observations: ObservationRecord[]): number;
 interface LlmArgs {

package/dist/memory/compaction.js

@@ -8,8 +8,8 @@ import { buildPrunerPassGuidance, buildReflectorPassGuidance, CONTEXT_USAGE_INST
 import { truncateRecordContent } from "./serialize.js";
 import { estimateStringTokens } from "./tokens.js";
 import { reflectionContent, reflectionToPromptLine } from "./types.js";
-export const REFLECTOR_MAX_PASSES = 2;
-export const PRUNER_MAX_PASSES = 2;
+export const REFLECTOR_MAX_PASSES = 1;
+export const PRUNER_MAX_PASSES = 2; // Kept for compatibility; deterministic pruner replaces this
 const PRUNER_TARGET_RATIO = 0.8;
 export function observationPoolTokens(observations) {
     return estimateStringTokens(observationsToPromptLines(observations).join("\n"));
@@ -293,7 +293,7 @@ function reflectorPassContext(pass) {
     return {
         pass,
         maxPasses: REFLECTOR_MAX_PASSES,
-        minSupportingObservationIds: pass === 1 ? 2 : 1,
+        minSupportingObservationIds: REFLECTOR_MAX_PASSES === 1 ? 1 : (pass === 1 ? 2 : 1),
     };
 }
 function reflectionContentKey(reflection) {

package/dist/memory/config.d.ts

@@ -1,3 +1,14 @@
+export type Relevance = "low" | "medium" | "high" | "critical";
+export interface InterAgentConfig {
+    /** Auto-broadcast captured observations/reflections to other sessions. Default: true. */
+    broadcastOnCompact?: boolean;
+    /** Minimum relevance to auto-broadcast. Default: "high". */
+    minBroadcastRelevance?: Relevance;
+    /** Auto-receive shared observations on session start. Default: true. */
+    autoReceive?: boolean;
+    /** TTL in seconds for observation messages. Default: 86400. */
+    ttlSeconds?: number;
+}
 export interface Config {
     observationThresholdTokens: number;
     compactionThresholdTokens: number;
@@ -14,6 +25,7 @@ export interface Config {
     prunerMaxTurnsPerPass?: number;
     /** @deprecated Use reflectorMaxTurnsPerPass and prunerMaxTurnsPerPass. */
     compactionMaxToolCalls?: number;
+    interAgent?: InterAgentConfig;
 }
 export interface EffectiveTurnLimits {
     observerMaxTurnsPerRun: number;

package/dist/memory/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/memory/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,MAAM;IACtB,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IACnC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,QAAQ,EAAE,MAOtB,CAAC;AAiCF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAMrE;AAED,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnF;AAaD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAUpF"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/memory/config.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAChC,yFAAyF;IACzF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,4DAA4D;IAC5D,qBAAqB,CAAC,EAAE,SAAS,CAAC;IAClC,wEAAwE;IACxE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,MAAM;IACtB,0BAA0B,EAAE,MAAM,CAAC;IACnC,yBAAyB,EAAE,MAAM,CAAC;IAClC,yBAAyB,EAAE,MAAM,CAAC;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IACnC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,QAAQ,EAAE,MAOtB,CAAC;AA0DF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,CAMrE;AAED,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnF;AAaD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAUpF"}

package/dist/memory/config.js

@@ -27,6 +27,24 @@ function normalizeTurnLimit(normalized, key) {
         normalized[key] = value;
     }
 }
+const RELEVANCE_VALUES = ["low", "medium", "high", "critical"];
+function normalizeInterAgentConfig(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const raw = value;
+    const normalized = {};
+    if (typeof raw.broadcastOnCompact === "boolean")
+        normalized.broadcastOnCompact = raw.broadcastOnCompact;
+    if (typeof raw.autoReceive === "boolean")
+        normalized.autoReceive = raw.autoReceive;
+    if (typeof raw.minBroadcastRelevance === "string" && RELEVANCE_VALUES.includes(raw.minBroadcastRelevance)) {
+        normalized.minBroadcastRelevance = raw.minBroadcastRelevance;
+    }
+    if (Number.isInteger(raw.ttlSeconds) && typeof raw.ttlSeconds === "number" && raw.ttlSeconds >= 0) {
+        normalized.ttlSeconds = raw.ttlSeconds;
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
 function normalizeSettingsConfig(value) {
     const normalized = { ...value };
     if ("passive" in normalized && typeof normalized.passive !== "boolean")
@@ -38,6 +56,15 @@ function normalizeSettingsConfig(value) {
     normalizeTurnLimit(normalized, "reflectorMaxTurnsPerPass");
     normalizeTurnLimit(normalized, "prunerMaxTurnsPerPass");
     normalizeTurnLimit(normalized, "compactionMaxToolCalls");
+    if ("interAgent" in normalized) {
+        const normalizedInterAgent = normalizeInterAgentConfig(normalized.interAgent);
+        if (normalizedInterAgent) {
+            normalized.interAgent = normalizedInterAgent;
+        }
+        else {
+            delete normalized.interAgent;
+        }
+    }
     return normalized;
 }
 export function resolveTurnLimits(config) {

package/dist/memory/deterministic-pruner.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic Pruner — replaces the 2-pass LLM-based pruner with a
+ * sorting algorithm that drops observations based on coverage, relevance,
+ * and age.
+ *
+ * The algorithm mirrors the LLM pruner's strategy:
+ *   1. Coverage-tagged observations (reinforced by reflections) drop first
+ *   2. Within same coverage: low > medium > high relevance
+ *   3. Within same relevance: oldest first (age-gradient rule)
+ *   4. Protected observations NEVER drop (critical, user assertions, completions)
+ *
+ * This eliminates ~2 LLM calls per compaction while producing equivalent results.
+ */
+import type { MemoryReflection, ObservationRecord } from "./types.js";
+export type CoverageTag = "reinforced" | "cited" | "uncited";
+export interface TaggedObservation {
+    observation: ObservationRecord;
+    coverage: CoverageTag;
+    /** Number of reflections that cite this observation */
+    citationCount: number;
+    /** True if this observation should never be dropped */
+    protected: boolean;
+    /** Reason for protection (for debugging) */
+    protectedReason?: string;
+}
+/**
+ * Compute coverage tags for all observations based on reflection citations.
+ * - reinforced: ≥4 reflections cite this observation
+ * - cited: 1-3 reflections cite this observation
+ * - uncited: no reflection cites this observation
+ */
+export declare function computeCoverageTags(observations: ObservationRecord[], reflections: MemoryReflection[]): Map<string, CoverageTag>;
+/**
+ * Tag observations with protection status.
+ */
+export declare function tagProtectedObservations(observations: ObservationRecord[]): Map<string, {
+    protected: boolean;
+    reason?: string;
+}>;
+export interface PrunerResult {
+    /** Kept observations */
+    observations: ObservationRecord[];
+    /** IDs of dropped observations */
+    droppedIds: string[];
+    /** Whether any protected observations were at risk of being dropped */
+    fellBack: boolean;
+    /** Tokens before pruning */
+    tokensBefore: number;
+    /** Tokens after pruning */
+    tokensAfter: number;
+}
+/**
+ * Deterministically prune an observation pool to fit within a token budget.
+ *
+ * Algorithm:
+ *   1. Compute coverage tags from reflection citations
+ *   2. Detect protected observations (critical, assertions, completions, errors, unique IDs)
+ *   3. Sort by droppability (reinforced+low+oldest first)
+ *   4. Drop from the sorted list until pool ≤ targetTokens
+ *   5. Never drop protected observations
+ *
+ * Target is 80% of the budget to leave breathing room for the summary text.
+ */
+export declare function deterministicPrune(observations: ObservationRecord[], reflections: MemoryReflection[], budgetTokens: number): PrunerResult;
+//# sourceMappingURL=deterministic-pruner.d.ts.map

package/dist/memory/deterministic-pruner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic-pruner.d.ts","sourceRoot":"","sources":["../../src/memory/deterministic-pruner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAStE,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,YAAY,EAAE,iBAAiB,EAAE,EACjC,WAAW,EAAE,gBAAgB,EAAE,GAC7B,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CA2B1B;AAuHD;;GAEG;AACH,wBAAgB,wBAAwB,CACvC,YAAY,EAAE,iBAAiB,EAAE,GAC/B,GAAG,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0CtD;AAoDD,MAAM,WAAW,YAAY;IAC5B,wBAAwB;IACxB,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,kCAAkC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,YAAY,EAAE,iBAAiB,EAAE,EACjC,WAAW,EAAE,gBAAgB,EAAE,EAC/B,YAAY,EAAE,MAAM,GAClB,YAAY,CA8Fd"}

package/dist/memory/deterministic-pruner.js

@@ -0,0 +1,333 @@
+/**
+ * Deterministic Pruner — replaces the 2-pass LLM-based pruner with a
+ * sorting algorithm that drops observations based on coverage, relevance,
+ * and age.
+ *
+ * The algorithm mirrors the LLM pruner's strategy:
+ *   1. Coverage-tagged observations (reinforced by reflections) drop first
+ *   2. Within same coverage: low > medium > high relevance
+ *   3. Within same relevance: oldest first (age-gradient rule)
+ *   4. Protected observations NEVER drop (critical, user assertions, completions)
+ *
+ * This eliminates ~2 LLM calls per compaction while producing equivalent results.
+ */
+import { estimateStringTokens } from "./tokens.js";
+import { debugLog, isDebugLogEnabled } from "./debug-log.js";
+/**
+ * Compute coverage tags for all observations based on reflection citations.
+ * - reinforced: ≥4 reflections cite this observation
+ * - cited: 1-3 reflections cite this observation
+ * - uncited: no reflection cites this observation
+ */
+export function computeCoverageTags(observations, reflections) {
+    const citationCounts = new Map();
+    // Initialize counts
+    for (const obs of observations) {
+        citationCounts.set(obs.id, 0);
+    }
+    // Count citations from reflections
+    for (const reflection of reflections) {
+        if (typeof reflection === "string" || reflection.legacy === true)
+            continue;
+        for (const obsId of reflection.supportingObservationIds) {
+            const count = citationCounts.get(obsId);
+            if (count !== undefined) {
+                citationCounts.set(obsId, count + 1);
+            }
+        }
+    }
+    // Compute tags
+    const tags = new Map();
+    for (const obs of observations) {
+        const count = citationCounts.get(obs.id) ?? 0;
+        tags.set(obs.id, count >= 4 ? "reinforced" : count >= 1 ? "cited" : "uncited");
+    }
+    return tags;
+}
+// ============================================================================
+// Protection Detection
+// ============================================================================
+/** Patterns indicating a user assertion (identity, preference, constraint). */
+const USER_ASSERTION_PATTERNS = [
+    /\buser\s+(stated|said|mentioned|confirmed|reported|asserted|told|specified)\b/i,
+    /\buser\s+(prefers|prefer|wants|needs|requires|insists|demands)\b/i,
+    /\buser\s+(is|has|was|will|can|does)\b/i,
+    /\buser\s+(decided|chose|picked|selected|opted)\b/i,
+];
+/** Patterns indicating a concrete completion that should not be redone. */
+const COMPLETION_PATTERNS = [
+    /\bcompleted[:\s]/i,
+    /\bresolved[:\s]/i,
+    /\bconfirmed working\b/i,
+    /\bfinished[:\s]/i,
+    /\bimplemented[:\s]/i,
+    /\bmerged[:\s]/i,
+    /\bdeployed[:\s]/i,
+    /\bfix(ed)?[:\s]/i,
+];
+/** Patterns indicating verbatim error messages. */
+const ERROR_PATTERNS = [
+    /\bTS\d{4,5}\b/, // TypeScript error codes
+    /\bE[A-Z]+\d+\b/, // Generic error codes
+    /\bError:\s/i,
+    /\bfailed[:\s]/i,
+    /\bpanic[:\s]/i,
+    /\bstack trace\b/i,
+    /\bat\s+\S+:\d+:\d+\b/, // Stack trace lines
+    /\bCannot\s+(find|read|write|open|access|parse|resolve)\b/i,
+    /\bnot\s+(found|supported|allowed|permitted|valid)\b/i,
+];
+/**
+ * Detect if an observation content contains a user assertion.
+ */
+function isUserAssertion(content) {
+    return USER_ASSERTION_PATTERNS.some((p) => p.test(content));
+}
+/**
+ * Detect if an observation content marks a concrete completion.
+ */
+function isCompletion(content) {
+    return COMPLETION_PATTERNS.some((p) => p.test(content));
+}
+/**
+ * Detect if an observation content contains a verbatim error.
+ */
+function isVerbatimError(content) {
+    return ERROR_PATTERNS.some((p) => p.test(content));
+}
+/**
+ * Detect if an observation contains unique identifiers that appear nowhere else.
+ * Checks for file paths, package names, commit SHAs, ticket IDs, error codes.
+ */
+function hasUniqueIdentifiers(observation, allObservations) {
+    // Extract potential identifiers
+    const identifiers = extractIdentifiers(observation.content);
+    if (identifiers.length === 0)
+        return false;
+    // Check if ANY of these identifiers appear in other observations
+    for (const id of identifiers) {
+        let foundElsewhere = false;
+        for (const other of allObservations) {
+            if (other.id === observation.id)
+                continue;
+            if (other.content.includes(id)) {
+                foundElsewhere = true;
+                break;
+            }
+        }
+        if (!foundElsewhere)
+            return true; // This identifier is unique to this observation
+    }
+    return false;
+}
+/**
+ * Extract potential identifiers from observation content.
+ * Looks for: file paths, package names, commit SHAs, ticket IDs, error codes.
+ */
+function extractIdentifiers(content) {
+    const ids = [];
+    // File paths: /path/to/file.ext or relative/path/file.ext or src/file.ts
+    const pathMatches = content.match(/\b[\w./-]+\.[\w]{1,10}\b/g);
+    if (pathMatches)
+        ids.push(...pathMatches);
+    // Package names: @scope/name or package-name
+    const pkgMatches = content.match(/@[\w-]+\/[\w-]+|\b[\w-]+-[\w-]+(?:\/[\w-]+)*\b/g);
+    if (pkgMatches)
+        ids.push(...pkgMatches);
+    // Commit SHAs: 7-40 hex chars
+    const shaMatches = content.match(/\b[a-f0-9]{7,40}\b/gi);
+    if (shaMatches)
+        ids.push(...shaMatches);
+    // Ticket IDs: PROJ-123 or #1234
+    const ticketMatches = content.match(/\b[A-Z]{2,}-\d+\b|#\d{3,}\b/g);
+    if (ticketMatches)
+        ids.push(...ticketMatches);
+    // Error codes: TS2322, ENOENT, etc.
+    const errorCodeMatches = content.match(/\b(?:TS|E[A-Z])\d{2,}\b/g);
+    if (errorCodeMatches)
+        ids.push(...errorCodeMatches);
+    // Deduplicate and filter very short/generic identifiers
+    return [...new Set(ids)].filter((id) => id.length > 4 && !/^[\d.]+$/.test(id));
+}
+/**
+ * Tag observations with protection status.
+ */
+export function tagProtectedObservations(observations) {
+    const protected_ = new Map();
+    for (const obs of observations) {
+        // Critical relevance is always protected
+        if (obs.relevance === "critical") {
+            protected_.set(obs.id, { protected: true, reason: "critical relevance" });
+            continue;
+        }
+        // User assertions about identity/preferences/constraints
+        if (isUserAssertion(obs.content)) {
+            protected_.set(obs.id, { protected: true, reason: "user assertion" });
+            continue;
+        }
+        // Concrete completions
+        if (isCompletion(obs.content)) {
+            protected_.set(obs.id, { protected: true, reason: "completion marker" });
+            continue;
+        }
+        // Verbatim errors
+        if (isVerbatimError(obs.content)) {
+            protected_.set(obs.id, { protected: true, reason: "verbatim error" });
+            continue;
+        }
+        // Unique identifiers (will be checked below)
+        protected_.set(obs.id, { protected: false });
+    }
+    // Second pass: check for unique identifiers across all observations
+    for (const obs of observations) {
+        const status = protected_.get(obs.id);
+        if (status?.protected)
+            continue; // Already protected
+        if (hasUniqueIdentifiers(obs, observations)) {
+            protected_.set(obs.id, { protected: true, reason: "unique identifiers" });
+        }
+    }
+    return protected_;
+}
+// ============================================================================
+// Sorting & Pruning
+// ============================================================================
+const COVERAGE_PRIORITY = {
+    reinforced: 0, // Drop first
+    cited: 1,
+    uncited: 2, // Drop last (among non-protected)
+};
+const RELEVANCE_PRIORITY = {
+    low: 0,
+    medium: 1,
+    high: 2,
+    critical: 3,
+};
+/**
+ * Sort observations for pruning: most droppable first, protected last.
+ *
+ * Priority order (ascending = drop first):
+ *   1. Coverage: reinforced → cited → uncited
+ *   2. Relevance: low → medium → high → critical
+ *   3. Age: oldest → newest
+ *   4. Protected: always last
+ */
+function sortForPruning(tagged) {
+    return [...tagged].sort((a, b) => {
+        // Protected always last
+        if (a.protected !== b.protected) {
+            return a.protected ? 1 : -1;
+        }
+        // Coverage priority
+        const covA = COVERAGE_PRIORITY[a.coverage];
+        const covB = COVERAGE_PRIORITY[b.coverage];
+        if (covA !== covB)
+            return covA - covB;
+        // Relevance priority
+        const relA = RELEVANCE_PRIORITY[a.observation.relevance] ?? 1;
+        const relB = RELEVANCE_PRIORITY[b.observation.relevance] ?? 1;
+        if (relA !== relB)
+            return relA - relB;
+        // Age: oldest first (lexicographic timestamp comparison)
+        const timeA = a.observation.timestamp ?? "";
+        const timeB = b.observation.timestamp ?? "";
+        return timeA.localeCompare(timeB);
+    });
+}
+/**
+ * Deterministically prune an observation pool to fit within a token budget.
+ *
+ * Algorithm:
+ *   1. Compute coverage tags from reflection citations
+ *   2. Detect protected observations (critical, assertions, completions, errors, unique IDs)
+ *   3. Sort by droppability (reinforced+low+oldest first)
+ *   4. Drop from the sorted list until pool ≤ targetTokens
+ *   5. Never drop protected observations
+ *
+ * Target is 80% of the budget to leave breathing room for the summary text.
+ */
+export function deterministicPrune(observations, reflections, budgetTokens) {
+    if (observations.length === 0) {
+        return {
+            observations: [],
+            droppedIds: [],
+            fellBack: false,
+            tokensBefore: 0,
+            tokensAfter: 0,
+        };
+    }
+    const targetTokens = Math.max(1, Math.floor(budgetTokens * 0.8));
+    const coverageTags = computeCoverageTags(observations, reflections);
+    const protectionStatus = tagProtectedObservations(observations);
+    // Build tagged observations
+    const tagged = observations.map((obs) => {
+        const coverage = coverageTags.get(obs.id) ?? "uncited";
+        const citationCount = [...reflections]
+            .filter((r) => typeof r !== "string" && !r.legacy)
+            .reduce((sum, r) => {
+            if (typeof r === "string")
+                return sum;
+            return sum + (r.supportingObservationIds.includes(obs.id) ? 1 : 0);
+        }, 0);
+        const prot = protectionStatus.get(obs.id);
+        return {
+            observation: obs,
+            coverage,
+            citationCount,
+            protected: prot?.protected ?? false,
+            protectedReason: prot?.reason,
+        };
+    });
+    const tokensBefore = observations.reduce((sum, o) => sum + estimateStringTokens(o.content), 0);
+    // If already under budget, no pruning needed
+    if (tokensBefore <= targetTokens) {
+        debugLog("deterministic_pruner.under_target", {
+            tokensBefore,
+            targetTokens,
+            observationCount: observations.length,
+        });
+        return {
+            observations,
+            droppedIds: [],
+            fellBack: false,
+            tokensBefore,
+            tokensAfter: tokensBefore,
+        };
+    }
+    // Sort for pruning
+    const sorted = sortForPruning(tagged);
+    // Drop from the front until budget is met
+    const dropped = new Set();
+    let currentTokens = tokensBefore;
+    for (const item of sorted) {
+        // Never drop protected observations
+        if (item.protected)
+            continue;
+        // Stop if we're under budget
+        if (currentTokens <= targetTokens)
+            break;
+        dropped.add(item.observation.id);
+        currentTokens -= estimateStringTokens(item.observation.content);
+    }
+    // Check if we couldn't reach the budget because too many observations are protected
+    const fellBack = currentTokens > targetTokens && dropped.size < sorted.filter((s) => !s.protected).length;
+    const kept = observations.filter((o) => !dropped.has(o.id));
+    const droppedIds = Array.from(dropped);
+    debugLog("deterministic_pruner.result", {
+        tokensBefore,
+        tokensAfter: currentTokens,
+        targetTokens,
+        dropped: droppedIds.length,
+        remaining: kept.length,
+        protectedCount: sorted.filter((s) => s.protected).length,
+        fellBack,
+        droppedIds: isDebugLogEnabled() ? droppedIds : undefined,
+    });
+    return {
+        observations: kept,
+        droppedIds,
+        fellBack,
+        tokensBefore,
+        tokensAfter: currentTokens,
+    };
+}

package/dist/memory/hooks/compaction-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA+C,MAAM,iCAAiC,CAAC;AAsBjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAmE7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA6XhF"}
+{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA+C,MAAM,iCAAiC,CAAC;AAoBjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAgE7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA0bhF"}