@animus-labs/cortex 0.2.0

package/dist/compaction/observational/index.d.ts

@@ -0,0 +1,219 @@
+/**
+ * ObservationalMemoryEngine: core orchestrator for the observational memory
+ * system.
+ *
+ * Ties together the observer, reflector, and buffering coordinator. Manages
+ * the observation slot, handles activation and reflection, and exposes the
+ * state management API.
+ *
+ * The engine runs inside CompactionManager's transformContext hook. It does
+ * NOT directly call ContextManager.setSlot(); instead, it manages the slot
+ * content string and the integration layer handles writing it to the slot.
+ *
+ * References:
+ *   - observational-memory-architecture.md
+ *   - compaction-strategy.md
+ *   - context-manager.md
+ */
+import type { CompleteFn } from '../compaction.js';
+import type { AgentMessage, AgentContext } from '../../context-manager.js';
+import type { ObservationalMemoryConfig, ObservationalMemoryState, ObservationEvent, ReflectionEvent, RecallConfig } from './types.js';
+export { BufferingCoordinator } from './buffering.js';
+export { runObserver } from './observer.js';
+export { runReflector, computeEffectiveReflectionThreshold } from './reflector.js';
+export { createRecallTool } from './recall-tool.js';
+export type { ObservationalMemoryConfig, ObservationalMemoryState, ObservationChunk, ObservationEvent, ReflectionEvent, ContinuationHint, RecallConfig, RecallResult, ObserverOutput, ReflectorOutput, BufferState, } from './types.js';
+/**
+ * Core orchestrator for the observational memory system.
+ *
+ * Coordinates the observer, reflector, and buffering coordinator to maintain
+ * a compressed observation log of the conversation. Called from
+ * CompactionManager during transformContext.
+ */
+export declare class ObservationalMemoryEngine {
+    private config;
+    private buffering;
+    private completeFn;
+    private observations;
+    private continuationHint;
+    private observationTokenCount;
+    private generationCount;
+    private contextWindow;
+    private utilityModelContextWindow;
+    private slotIndex;
+    private logger;
+    private observationHandlers;
+    private reflectionHandlers;
+    constructor(config: Partial<ObservationalMemoryConfig>, slotIndex: number);
+    /**
+     * Set the LLM completion function (wired to utilityComplete on CortexAgent).
+     */
+    setCompleteFn(fn: CompleteFn): void;
+    /**
+     * Update the context window size.
+     */
+    setContextWindow(contextWindow: number): void;
+    /**
+     * Update the utility model context window (for clamps).
+     */
+    setUtilityModelContextWindow(utilityModelContextWindow: number): void;
+    /**
+     * Set the logger.
+     */
+    setLogger(logger: {
+        warn: (msg: string) => void;
+        info: (msg: string) => void;
+    }): void;
+    /**
+     * Register an observation event handler.
+     */
+    onObservation(handler: (event: ObservationEvent) => void): void;
+    /**
+     * Register a reflection event handler.
+     */
+    onReflection(handler: (event: ReflectionEvent) => void): void;
+    /**
+     * Core method called from CompactionManager during transformContext.
+     *
+     * Handles observation activation and reflection when context utilization
+     * exceeds the activation threshold. Updates the observation slot and
+     * trims observed messages from history.
+     *
+     * @param context - The AgentContext from transformContext
+     * @param utilization - Current total context utilization (0-1)
+     * @param slotCount - Number of slot messages at the start of the array
+     * @param getHistory - Get conversation history from the context (post-slot)
+     * @param setHistory - Set conversation history in the context (post-slot)
+     * @param getSourceHistory - Get the original transcript history (agent.state.messages post-slot)
+     * @param setSourceHistory - Replace the original transcript history
+     * @returns Modified context with updated observations and trimmed history
+     */
+    applyInTransformContext(context: AgentContext, utilization: number, slotCount: number, getHistory: (ctx: AgentContext) => AgentMessage[], setHistory: (ctx: AgentContext, history: AgentMessage[]) => AgentContext, getSourceHistory: () => AgentMessage[], setSourceHistory: (history: AgentMessage[]) => void): Promise<AgentContext>;
+    /**
+     * Called at each turn_end event. Handles async buffer triggering.
+     *
+     * Computes the dynamic buffer interval and launches an async observer
+     * if enough unobserved tokens have accumulated.
+     *
+     * @param totalTokens - Total tokens from the last LLM response
+     * @param contextWindow - Current context window size
+     * @param messages - Current conversation messages (post-slot)
+     * @param slotCount - Number of slot messages
+     */
+    onTurnEnd(totalTokens: number, contextWindow: number, messages: AgentMessage[], slotCount: number): void;
+    /**
+     * Build the full observation slot content.
+     *
+     * Assembles the preamble, optional recall instructions, observation block,
+     * and optional continuation hints into a single string.
+     */
+    buildSlotContent(): string;
+    /**
+     * Estimate the full slot content size for a given observation text.
+     *
+     * Used by the post-chunk utilization estimate to account for slot
+     * overhead (preamble, XML wrappers, continuation hints) rather than
+     * just the raw observation text.
+     */
+    private buildSlotContentForEstimate;
+    /**
+     * Force a synchronous observation cycle.
+     *
+     * Used by consumers after critical corrections to ensure the observation
+     * log captures the correction immediately.
+     *
+     * @param messages - The full message array (may include slot messages)
+     * @param slotCount - Number of slot messages to skip
+     */
+    triggerObservation(messages: AgentMessage[], slotCount: number): Promise<void>;
+    /**
+     * Kick off an initial async buffer on unobserved messages.
+     * Called during session resumption for a head start before the first prompt().
+     */
+    kickstartBuffer(messages: AgentMessage[], slotCount: number): void;
+    /**
+     * Returns the current state for session persistence.
+     */
+    getState(): ObservationalMemoryState;
+    /**
+     * Restore state from a previous session.
+     *
+     * Sets observations, continuation hint, token count, and generation count.
+     * Restores buffering state. If a completeFn is available and observations
+     * exist, updates the slot content. Kicks off an initial async buffer on
+     * unobserved messages as a non-blocking head start.
+     */
+    restoreState(state: ObservationalMemoryState): void;
+    /**
+     * Returns the current slot content string.
+     */
+    getSlotContent(): string;
+    /**
+     * Returns just the observation text.
+     */
+    getObservations(): string;
+    /**
+     * Token count of activated observations only.
+     */
+    getObservationTokenCount(): number;
+    /**
+     * Whether the observer or reflector is currently running in the background.
+     */
+    isProcessing(): boolean;
+    /**
+     * Whether the observer specifically is in-flight.
+     */
+    isObserverInFlight(): boolean;
+    /**
+     * Whether the reflector specifically is in-flight.
+     */
+    isReflectorInFlight(): boolean;
+    /**
+     * Abort all in-flight operations. Delegates to buffering.abort().
+     */
+    abort(): void;
+    /**
+     * Whether recall is configured.
+     */
+    hasRecall(): boolean;
+    /**
+     * Get the recall config if provided.
+     */
+    getRecallConfig(): RecallConfig | undefined;
+    /**
+     * Check and handle reflection after observation activation.
+     *
+     * Determines whether reflection should run (sync, async, or none) based
+     * on the current observation token count relative to the effective
+     * reflection threshold.
+     */
+    private handleReflection;
+    /**
+     * Build the observer config object without assigning undefined to optional
+     * properties (exactOptionalPropertyTypes is enabled).
+     */
+    private buildObserverConfig;
+    /**
+     * Build the reflector config object without assigning undefined to optional
+     * properties (exactOptionalPropertyTypes is enabled).
+     */
+    private buildReflectorConfig;
+    /**
+     * Merge buffered observation chunks into a single observation text.
+     *
+     * Concatenates all chunk observation texts with double newlines. Uses
+     * the latest chunk's currentTask and suggestedResponse (latest wins).
+     */
+    private mergeChunks;
+    /**
+     * Fire all observation handlers. Each handler is individually try/catch
+     * wrapped to prevent one handler from breaking others.
+     */
+    private fireObservationEvent;
+    /**
+     * Fire all reflection handlers. Each handler is individually try/catch
+     * wrapped to prevent one handler from breaking others.
+     */
+    private fireReflectionEvent;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/compaction/observational/index.d.ts.map

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