@animalabs/context-manager 0.1.0

package/dist/src/context-manager.d.ts

@@ -0,0 +1,245 @@
+import { JsStore } from '@animalabs/chronicle';
+import type { Membrane, ContentBlock } from '@animalabs/membrane';
+import type { MessageId, Sequence, MessageMetadata, StoredMessage, TokenBudget, PendingWork, BranchInfo, ContextStrategy, MessageQuery, MessageQueryResult, ContextInjection, CompileResult } from './types/index.js';
+/**
+ * Base configuration for ContextManager.
+ */
+interface ContextManagerBaseConfig {
+    /** Initial strategy (default: PassthroughStrategy) */
+    strategy?: ContextStrategy;
+    /** Membrane instance for compression strategies */
+    membrane?: Membrane;
+    /** Token estimator function */
+    tokenEstimator?: (text: string) => number;
+    /**
+     * Namespace for multi-agent support.
+     * When set, the context log uses state ID `{namespace}/context`.
+     * Messages remain shared (no namespace) unless `isolate` is true.
+     */
+    namespace?: string;
+    /**
+     * When true, the namespace applies to messages as well as the context log,
+     * giving fully isolated state: `{namespace}/messages` + `{namespace}/context`.
+     * Use for subagents that should not share message state with the parent.
+     * Requires `namespace` to be set.
+     */
+    isolate?: boolean;
+    /**
+     * When true, log the compiled context to stderr for debugging.
+     */
+    debugLogContext?: boolean;
+}
+/**
+ * Configuration when ContextManager creates and owns the store.
+ */
+interface ContextManagerPathConfig extends ContextManagerBaseConfig {
+    /** Path to Chronicle store */
+    path: string;
+    /** Blob cache size (default: 1000) */
+    blobCacheSize?: number;
+    store?: never;
+}
+/**
+ * Configuration when app provides an existing store.
+ * App retains ownership and is responsible for closing the store.
+ */
+interface ContextManagerStoreConfig extends ContextManagerBaseConfig {
+    /** Existing Chronicle store (app-owned) */
+    store: JsStore;
+    path?: never;
+    blobCacheSize?: never;
+}
+/**
+ * Configuration for ContextManager.
+ */
+export type ContextManagerConfig = ContextManagerPathConfig | ContextManagerStoreConfig;
+/**
+ * Context Manager - the main interface for managing conversation context.
+ *
+ * Sits between the application/agent layer and Membrane, managing what goes
+ * into the context window. Uses Chronicle for persistent storage.
+ */
+export declare class ContextManager {
+    private store;
+    private messageStore;
+    private contextLog;
+    private strategy;
+    private membrane?;
+    private initialized;
+    /** Whether we own the store (created it) vs app owns it (passed in) */
+    private ownsStore;
+    private debugLogContext;
+    private constructor();
+    /**
+     * Open or create a context manager.
+     *
+     * Can be called with either:
+     * - `{ path: string }` - Creates and owns a new store
+     * - `{ store: JsStore }` - Uses an existing app-owned store
+     *
+     * When using an app-owned store, the app is responsible for closing it.
+     * The app can register additional states on the store before passing it.
+     */
+    static open(config: ContextManagerConfig): Promise<ContextManager>;
+    /**
+     * Add a message to the store.
+     */
+    addMessage(participant: string, content: ContentBlock[], metadata?: MessageMetadata, causedBy?: MessageId[]): MessageId;
+    /**
+     * Edit a message in the store. Propagates to context log based on source relation.
+     */
+    editMessage(messageId: MessageId, content: ContentBlock[]): void;
+    /**
+     * Remove a message from the store. Propagates to context log.
+     */
+    removeMessage(messageId: MessageId): void;
+    /**
+     * Remove a range of messages from the store.
+     */
+    removeMessages(fromId: MessageId, toId: MessageId): void;
+    /**
+     * Get a message by ID.
+     */
+    getMessage(messageId: MessageId): StoredMessage | null;
+    /**
+     * Get a message as it was at a specific sequence (time travel).
+     */
+    getMessageAt(messageId: MessageId, atSequence: Sequence): StoredMessage | null;
+    /**
+     * Get all messages in the store.
+     */
+    getAllMessages(): StoredMessage[];
+    /**
+     * Query messages by filter criteria.
+     * Useful for finding messages from external sources, by participant, etc.
+     *
+     * @example
+     * // Find all messages from Discord
+     * const { messages } = manager.queryMessages({ source: 'discord' });
+     *
+     * @example
+     * // Find messages from a specific channel
+     * const { messages } = manager.queryMessages({
+     *   source: 'discord',
+     *   metadata: { 'external.channelId': '123456' }
+     * });
+     *
+     * @example
+     * // Find specific messages by external ID
+     * const { messages } = manager.queryMessages({
+     *   source: 'discord',
+     *   externalIds: ['msg1', 'msg2', 'msg3']
+     * });
+     */
+    queryMessages(filter: MessageQuery): MessageQueryResult;
+    /**
+     * Find a message by its external source and ID.
+     * Returns the internal message ID, or null if not found.
+     */
+    findMessageByExternalId(source: string, externalId: string): MessageId | null;
+    /**
+     * Create a branch from a specific message.
+     * The new branch will have state as of that message's sequence (time-travel branching).
+     */
+    branchAt(messageId: MessageId, name?: string): string;
+    /**
+     * Switch to a different branch.
+     */
+    switchBranch(branchId: string): void;
+    /**
+     * Get current branch.
+     */
+    currentBranch(): BranchInfo;
+    /**
+     * List all branches.
+     */
+    listBranches(): BranchInfo[];
+    /**
+     * Check if compile() will block waiting for background work.
+     */
+    isReady(): boolean;
+    /**
+     * Get info about pending background work.
+     */
+    getPendingWork(): PendingWork | null;
+    /**
+     * Compile context for Membrane.
+     *
+     * Accepts optional context injections (e.g., from MCPL servers) and merges
+     * them into the compiled output by position:
+     * - "system": returned separately in `systemInjections` (caller appends to system prompt)
+     * - "beforeUser": inserted before the last user message
+     * - "afterUser": inserted after the last user message
+     *
+     * May block if strategy has pending work.
+     */
+    compile(budget?: TokenBudget, injections?: ContextInjection[]): Promise<CompileResult>;
+    /**
+     * Log the compiled context to stderr for debugging.
+     * Uses stderr so it doesn't pollute the context log (which strategies read).
+     */
+    private logCompiledContext;
+    /**
+     * Set the context management strategy.
+     */
+    setStrategy(strategy: ContextStrategy): Promise<void>;
+    /**
+     * Get the current strategy.
+     */
+    getStrategy(): ContextStrategy;
+    /**
+     * Reset the head window to start from a new position.
+     * Old head window messages become compressible.
+     *
+     * If transitionText is provided, it's used as the transition summary.
+     * If omitted, an LLM call auto-generates a transition summary.
+     *
+     * Returns the transition summary text used.
+     */
+    resetHeadWindow(transitionText?: string): Promise<string>;
+    /**
+     * Trigger background maintenance work.
+     * Call this periodically to allow strategies to do compression, etc.
+     */
+    tick(): Promise<void>;
+    private initializeStrategy;
+    private createStrategyContext;
+    /**
+     * Handle message store events for edit propagation.
+     */
+    private handleMessageStoreEvent;
+    private handleMessageAdd;
+    private handleMessageEdit;
+    private handleMessageRemove;
+    /**
+     * Get the underlying Chronicle store.
+     * Useful for registering additional states or accessing store-level features.
+     */
+    getStore(): JsStore;
+    /**
+     * Sync to disk.
+     */
+    sync(): void;
+    /**
+     * Close the context manager.
+     *
+     * If the manager owns the store (created via path config), this closes the store.
+     * If the app owns the store (passed via store config), this is a no-op;
+     * the app is responsible for closing the store when done.
+     */
+    close(): void;
+    /**
+     * Check if the store has been closed.
+     */
+    isClosed(): boolean;
+    /**
+     * Get store stats.
+     */
+    stats(): {
+        messageCount: number;
+        contextEntryCount: number;
+        branches: number;
+    };
+}
+export {};
+//# sourceMappingURL=context-manager.d.ts.map

package/dist/src/context-manager.d.ts.map

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