claude-cognitive 0.1.0

package/dist/promotion.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Observation promotion logic for claude-cognitive.
+ * Handles auto-promotion of high-confidence observations to semantic memory.
+ * @module promotion
+ */
+import type { Observation, TypedEventEmitter } from "./events.js";
+import type { SemanticMemory } from "./semantic.js";
+import type { Opinion } from "./types.js";
+/** Default confidence threshold for auto-promotion */
+export declare const DEFAULT_PROMOTION_THRESHOLD = 0.9;
+/** Options for the PromotionManager */
+export interface PromotionOptions {
+    /** Confidence threshold for auto-promotion (default: 0.9) */
+    threshold?: number;
+    /** Whether to deduplicate similar observations (default: true) */
+    deduplicate?: boolean;
+    /** Similarity threshold for deduplication (0-1, default: 0.8) */
+    similarityThreshold?: number;
+}
+/** Result of a promotion attempt */
+export interface PromotionResult {
+    /** Whether the observation was promoted */
+    promoted: boolean;
+    /** Reason if not promoted */
+    reason?: "below_threshold" | "duplicate" | "error";
+    /** Error message if promotion failed */
+    error?: string;
+}
+/**
+ * Manages observation promotion to semantic memory.
+ *
+ * Listens for opinion:formed events and auto-promotes observations
+ * that meet the confidence threshold.
+ *
+ * @example
+ * ```typescript
+ * const manager = new PromotionManager(semanticMemory, mind, {
+ *   threshold: 0.9
+ * });
+ *
+ * // Manager automatically listens to mind events
+ * // Or promote manually:
+ * await manager.promote({
+ *   text: "Auth changes need nav updates",
+ *   confidence: 0.95,
+ *   source: "reflect"
+ * });
+ * ```
+ */
+export declare class PromotionManager {
+    private readonly semantic;
+    private readonly emitter;
+    private readonly options;
+    /** Track promoted texts to prevent duplicates within session */
+    private promotedTexts;
+    /** Bound handler for cleanup */
+    private boundHandleOpinion;
+    constructor(semantic: SemanticMemory, emitter: TypedEventEmitter, options?: PromotionOptions);
+    /**
+     * Start listening for opinion events and auto-promote.
+     *
+     * Call this after Mind initialization to enable auto-promotion.
+     */
+    startListening(): void;
+    /**
+     * Stop listening for opinion events.
+     */
+    stopListening(): void;
+    /**
+     * Manually promote an observation.
+     *
+     * @param observation - Observation to promote
+     * @returns Result of promotion attempt
+     */
+    promote(observation: Observation): Promise<PromotionResult>;
+    /**
+     * Get the current promotion threshold.
+     */
+    getThreshold(): number;
+    /**
+     * Handle an opinion event and potentially promote it.
+     * @internal
+     */
+    private handleOpinion;
+    /**
+     * Normalize text for comparison.
+     * @internal
+     */
+    private normalizeText;
+    /**
+     * Check if text is similar to existing content.
+     * Uses simple word overlap for efficiency.
+     * @internal
+     */
+    private isSimilar;
+    /**
+     * Clear the session's promoted texts cache.
+     * Call this at session end if needed.
+     */
+    clearCache(): void;
+}
+/**
+ * Create an Observation from an Opinion.
+ *
+ * Convenience function for converting between types.
+ */
+export declare function opinionToObservation(opinion: Opinion, source?: string): Observation;
+/**
+ * Check if an opinion meets the promotion threshold.
+ */
+export declare function shouldPromote(opinion: Opinion, threshold?: number): boolean;
+//# sourceMappingURL=promotion.d.ts.map

package/dist/promotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion.d.ts","sourceRoot":"","sources":["../src/promotion.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAM1C,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAM/C,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAC;IAClB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,iBAAiB,GAAG,WAAW,GAAG,OAAO,CAAC;IACnD,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,gEAAgE;IAChE,OAAO,CAAC,aAAa,CAA0B;IAE/C,gCAAgC;IAChC,OAAO,CAAC,kBAAkB,CAAsC;gBAG9D,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,gBAAqB;IAchC;;;;OAIG;IACH,cAAc,IAAI,IAAI;IAItB;;OAEG;IACH,aAAa,IAAI,IAAI;IAIrB;;;;;OAKG;IACG,OAAO,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;IAmDjE;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;;OAGG;YACW,aAAa;IAU3B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAQrB;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAmBjB;;;OAGG;IACH,UAAU,IAAI,IAAI;CAGnB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,MAAM,GAAE,MAAkB,GACzB,WAAW,CAMb;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,MAAoC,GAC9C,OAAO,CAET"}

package/dist/promotion.js

@@ -0,0 +1,196 @@
+/**
+ * Observation promotion logic for claude-cognitive.
+ * Handles auto-promotion of high-confidence observations to semantic memory.
+ * @module promotion
+ */
+// ============================================
+// Constants
+// ============================================
+/** Default confidence threshold for auto-promotion */
+export const DEFAULT_PROMOTION_THRESHOLD = 0.9;
+// ============================================
+// PromotionManager Class
+// ============================================
+/**
+ * Manages observation promotion to semantic memory.
+ *
+ * Listens for opinion:formed events and auto-promotes observations
+ * that meet the confidence threshold.
+ *
+ * @example
+ * ```typescript
+ * const manager = new PromotionManager(semanticMemory, mind, {
+ *   threshold: 0.9
+ * });
+ *
+ * // Manager automatically listens to mind events
+ * // Or promote manually:
+ * await manager.promote({
+ *   text: "Auth changes need nav updates",
+ *   confidence: 0.95,
+ *   source: "reflect"
+ * });
+ * ```
+ */
+export class PromotionManager {
+    semantic;
+    emitter;
+    options;
+    /** Track promoted texts to prevent duplicates within session */
+    promotedTexts = new Set();
+    /** Bound handler for cleanup */
+    boundHandleOpinion;
+    constructor(semantic, emitter, options = {}) {
+        this.semantic = semantic;
+        this.emitter = emitter;
+        this.options = {
+            threshold: options.threshold ?? DEFAULT_PROMOTION_THRESHOLD,
+            deduplicate: options.deduplicate ?? true,
+            similarityThreshold: options.similarityThreshold ?? 0.8,
+        };
+        // Bind handler once for proper removal
+        this.boundHandleOpinion = this.handleOpinion.bind(this);
+    }
+    /**
+     * Start listening for opinion events and auto-promote.
+     *
+     * Call this after Mind initialization to enable auto-promotion.
+     */
+    startListening() {
+        this.emitter.on("opinion:formed", this.boundHandleOpinion);
+    }
+    /**
+     * Stop listening for opinion events.
+     */
+    stopListening() {
+        this.emitter.off("opinion:formed", this.boundHandleOpinion);
+    }
+    /**
+     * Manually promote an observation.
+     *
+     * @param observation - Observation to promote
+     * @returns Result of promotion attempt
+     */
+    async promote(observation) {
+        // Check threshold
+        if (observation.confidence < this.options.threshold) {
+            return {
+                promoted: false,
+                reason: "below_threshold",
+            };
+        }
+        // Check for duplicates
+        if (this.options.deduplicate) {
+            const normalized = this.normalizeText(observation.text);
+            if (this.promotedTexts.has(normalized)) {
+                return {
+                    promoted: false,
+                    reason: "duplicate",
+                };
+            }
+            // Check existing observations in semantic memory
+            if (this.semantic.isLoaded()) {
+                const existing = this.semantic.get("Observations") ?? "";
+                if (this.isSimilar(observation.text, existing)) {
+                    return {
+                        promoted: false,
+                        reason: "duplicate",
+                    };
+                }
+            }
+        }
+        // Perform promotion
+        try {
+            await this.semantic.promoteObservation(observation);
+            this.promotedTexts.add(this.normalizeText(observation.text));
+            // Emit event
+            this.emitter.emit("observation:promoted", observation);
+            return { promoted: true };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                promoted: false,
+                reason: "error",
+                error: msg,
+            };
+        }
+    }
+    /**
+     * Get the current promotion threshold.
+     */
+    getThreshold() {
+        return this.options.threshold;
+    }
+    /**
+     * Handle an opinion event and potentially promote it.
+     * @internal
+     */
+    async handleOpinion(opinion) {
+        const observation = {
+            text: opinion.opinion,
+            confidence: opinion.confidence,
+            source: "reflect",
+        };
+        await this.promote(observation);
+    }
+    /**
+     * Normalize text for comparison.
+     * @internal
+     */
+    normalizeText(text) {
+        return text
+            .toLowerCase()
+            .replace(/[^\w\s]/g, "")
+            .replace(/\s+/g, " ")
+            .trim();
+    }
+    /**
+     * Check if text is similar to existing content.
+     * Uses simple word overlap for efficiency.
+     * @internal
+     */
+    isSimilar(newText, existingContent) {
+        const newWords = new Set(this.normalizeText(newText).split(" "));
+        const existingWords = new Set(this.normalizeText(existingContent).split(" "));
+        if (newWords.size === 0)
+            return false;
+        let overlap = 0;
+        for (const word of newWords) {
+            if (existingWords.has(word)) {
+                overlap++;
+            }
+        }
+        const similarity = overlap / newWords.size;
+        return similarity >= this.options.similarityThreshold;
+    }
+    /**
+     * Clear the session's promoted texts cache.
+     * Call this at session end if needed.
+     */
+    clearCache() {
+        this.promotedTexts.clear();
+    }
+}
+// ============================================
+// Utility Functions
+// ============================================
+/**
+ * Create an Observation from an Opinion.
+ *
+ * Convenience function for converting between types.
+ */
+export function opinionToObservation(opinion, source = "reflect") {
+    return {
+        text: opinion.opinion,
+        confidence: opinion.confidence,
+        source,
+    };
+}
+/**
+ * Check if an opinion meets the promotion threshold.
+ */
+export function shouldPromote(opinion, threshold = DEFAULT_PROMOTION_THRESHOLD) {
+    return opinion.confidence >= threshold;
+}
+//# sourceMappingURL=promotion.js.map

package/dist/promotion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promotion.js","sourceRoot":"","sources":["../src/promotion.ts"],"names":[],"mappings":"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"}

package/dist/retry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Retry logic with exponential backoff for claude-cognitive.
+ * @module retry
+ */
+/**
+ * Options for retry behavior.
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts: number;
+    /** Initial delay in milliseconds (default: 100) */
+    initialDelayMs: number;
+    /** Maximum delay in milliseconds (default: 5000) */
+    maxDelayMs: number;
+    /** Exponential backoff multiplier (default: 2) */
+    backoffMultiplier: number;
+    /** Add random jitter to prevent thundering herd (default: true) */
+    jitter: boolean;
+    /**
+     * Custom function to determine if error is retryable.
+     * If not provided, uses HindsightError.isRetryable or defaults to false.
+     */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    /**
+     * Callback invoked before each retry attempt.
+     * Useful for logging or metrics.
+     */
+    onRetry?: (error: Error, attempt: number, delayMs: number) => void;
+}
+/**
+ * Execute a function with retry logic and exponential backoff.
+ *
+ * Retries are attempted when:
+ * 1. The error has `isRetryable: true` (for HindsightError)
+ * 2. The custom `shouldRetry` function returns true
+ * 3. The error is a TimeoutError
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration options
+ * @returns The result of the function
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => client.recall(bankId, query),
+ *   { maxAttempts: 3 }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: Partial<RetryOptions>): Promise<T>;
+/**
+ * Create a retryable version of an async function.
+ *
+ * @param fn - The async function to wrap
+ * @param options - Retry configuration options
+ * @returns A wrapped function that automatically retries on failure
+ *
+ * @example
+ * ```typescript
+ * const retryableRecall = createRetryable(
+ *   (query: string) => client.recall(bankId, query),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * const result = await retryableRecall('authentication flow');
+ * ```
+ */
+export declare function createRetryable<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => Promise<TResult>, options?: Partial<RetryOptions>): (...args: TArgs) => Promise<TResult>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpE;AA0DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM,GAClC,OAAO,CAAC,CAAC,CAAC,CAkCZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAC9D,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,EACxC,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM,GAClC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAEtC"}

package/dist/retry.js

@@ -0,0 +1,122 @@
+/**
+ * Retry logic with exponential backoff for claude-cognitive.
+ * @module retry
+ */
+import { HindsightError } from "./errors.js";
+const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 3,
+    initialDelayMs: 100,
+    maxDelayMs: 5000,
+    backoffMultiplier: 2,
+    jitter: true,
+};
+/**
+ * Sleep for a given number of milliseconds.
+ * @internal
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Check if an error is retryable using default logic.
+ * @internal
+ */
+function isDefaultRetryable(error) {
+    // Check for HindsightError.isRetryable
+    if (HindsightError.isHindsightError(error)) {
+        return error.isRetryable;
+    }
+    // Retry on timeout errors
+    if (error.name === "TimeoutError") {
+        return true;
+    }
+    // Don't retry unknown errors by default
+    return false;
+}
+/**
+ * Calculate delay for a given attempt with exponential backoff.
+ * @internal
+ */
+function calculateDelay(attempt, opts) {
+    // Exponential: initialDelay * multiplier^(attempt-1)
+    const exponentialDelay = opts.initialDelayMs * Math.pow(opts.backoffMultiplier, attempt - 1);
+    // Cap at maxDelay
+    const cappedDelay = Math.min(exponentialDelay, opts.maxDelayMs);
+    // Add jitter (0-50% of delay) to prevent thundering herd
+    if (opts.jitter) {
+        const jitterRange = cappedDelay * 0.5;
+        return Math.floor(cappedDelay + Math.random() * jitterRange);
+    }
+    return cappedDelay;
+}
+/**
+ * Execute a function with retry logic and exponential backoff.
+ *
+ * Retries are attempted when:
+ * 1. The error has `isRetryable: true` (for HindsightError)
+ * 2. The custom `shouldRetry` function returns true
+ * 3. The error is a TimeoutError
+ *
+ * @param fn - The async function to execute
+ * @param options - Retry configuration options
+ * @returns The result of the function
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => client.recall(bankId, query),
+ *   { maxAttempts: 3 }
+ * );
+ * ```
+ */
+export async function withRetry(fn, options = {}) {
+    const opts = { ...DEFAULT_RETRY_OPTIONS, ...options };
+    let lastError;
+    for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if we should retry
+            const isRetryable = opts.shouldRetry
+                ? opts.shouldRetry(lastError, attempt)
+                : isDefaultRetryable(lastError);
+            // If not retryable or last attempt, throw immediately
+            if (!isRetryable || attempt === opts.maxAttempts) {
+                throw lastError;
+            }
+            // Calculate delay with exponential backoff
+            const delay = calculateDelay(attempt, opts);
+            // Invoke onRetry callback if provided
+            if (opts.onRetry) {
+                opts.onRetry(lastError, attempt, delay);
+            }
+            await sleep(delay);
+        }
+    }
+    // Should never reach here, but TypeScript needs this
+    throw lastError ?? new Error("Retry failed");
+}
+/**
+ * Create a retryable version of an async function.
+ *
+ * @param fn - The async function to wrap
+ * @param options - Retry configuration options
+ * @returns A wrapped function that automatically retries on failure
+ *
+ * @example
+ * ```typescript
+ * const retryableRecall = createRetryable(
+ *   (query: string) => client.recall(bankId, query),
+ *   { maxAttempts: 3 }
+ * );
+ *
+ * const result = await retryableRecall('authentication flow');
+ * ```
+ */
+export function createRetryable(fn, options = {}) {
+    return (...args) => withRetry(() => fn(...args), options);
+}
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}