@animus-labs/cortex 0.2.0

package/dist/context-manager.d.ts

@@ -0,0 +1,134 @@
+/**
+ * ContextManager: slot-based persistent context + ephemeral per-call injection.
+ *
+ * Manages the content an agent sees through two mechanisms:
+ * - **Slots**: Named content blocks at the start of the message array.
+ *   Persistent, updated immediately via setSlot(). Ordered by stability
+ *   (most stable first) for prefix cache optimization.
+ * - **Ephemeral context**: Per-call content injected via transformContext.
+ *   Never stored in agent.state.messages. Rebuilt every LLM call.
+ *
+ * Message array layout:
+ *   [SLOT REGION (0..N-1)] [CONVERSATION HISTORY] [EPHEMERAL (in transformContext)] [PROMPT]
+ *
+ * Reference: context-manager.md
+ */
+import type { ContextManagerConfig } from './types.js';
+/**
+ * Minimal interface for pi-agent-core's Agent.state.messages entries.
+ * The actual type is Message from @earendil-works/pi-ai, but we define
+ * only what we need to avoid a hard dependency.
+ */
+export interface AgentMessage {
+    role: 'user' | 'assistant' | 'toolResult';
+    content: string | Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    toolCallId?: string;
+    toolName?: string;
+    details?: unknown;
+    isError?: boolean;
+    /** Epoch milliseconds when this message was created. Stamped by Cortex at turn boundaries. */
+    timestamp: number;
+}
+/**
+ * Minimal interface for pi-agent-core's Agent to access state.messages.
+ * We only need to read and write the messages array.
+ */
+export interface AgentStateAccessor {
+    state: {
+        messages: AgentMessage[];
+        systemPrompt?: string;
+        model?: unknown;
+        thinkingLevel?: string;
+        tools?: unknown[];
+        error?: string;
+        errorMessage?: string;
+    };
+}
+/**
+ * The context object passed to transformContext hooks.
+ * Mirrors pi-agent-core's AgentContext shape.
+ */
+export interface AgentContext {
+    systemPrompt: string;
+    model: unknown;
+    messages: AgentMessage[];
+    tools: unknown[];
+    thinkingLevel: string;
+}
+export declare class ContextManager {
+    private readonly agent;
+    private readonly slotNames;
+    private readonly slotIndexMap;
+    private ephemeralContent;
+    /**
+     * Create a ContextManager.
+     *
+     * @param agent - The pi-agent-core Agent instance (or any object with state.messages)
+     * @param config - Configuration with ordered slot names
+     */
+    constructor(agent: AgentStateAccessor, config: ContextManagerConfig);
+    /**
+     * The number of context slots.
+     */
+    get slotCount(): number;
+    /**
+     * The ordered slot names (frozen copy).
+     */
+    get slots(): readonly string[];
+    /**
+     * Update a slot's content. Immediately updates the corresponding
+     * message in agent.state.messages at the slot's position.
+     *
+     * @param name - The slot name (must match a name from the config)
+     * @param content - The raw string content (consumer handles formatting)
+     * @throws Error if the slot name is not recognized
+     */
+    setSlot(name: string, content: string): void;
+    /**
+     * Read current slot content.
+     *
+     * @param name - The slot name
+     * @returns The slot's content string, or null if the slot has not been set
+     * @throws Error if the slot name is not recognized
+     */
+    getSlot(name: string): string | null;
+    /**
+     * Set ephemeral content for the next LLM call(s).
+     * Injected at the end of the message array inside the transformContext hook.
+     * Never written to agent.state.messages.
+     * Pass null to clear.
+     *
+     * @param content - The ephemeral content string, or null to clear
+     */
+    setEphemeral(content: string | null): void;
+    /**
+     * Get the current ephemeral content.
+     *
+     * @returns The ephemeral content, or null if not set
+     */
+    getEphemeral(): string | null;
+    /**
+     * Returns a transformContext hook function that appends ephemeral content.
+     *
+     * The hook is composable: the consumer can chain it with other transformContext
+     * logic (compaction, skill buffer, etc.).
+     *
+     * The ephemeral content is appended as a user-role message at the end of
+     * the messages array, after all conversation history but before the prompt.
+     * This placement ensures it does not invalidate the prefix cache for
+     * content above it.
+     *
+     * @returns A function suitable for use as a transformContext hook
+     */
+    getTransformContextHook(): (context: AgentContext) => AgentContext;
+    /**
+     * Initialize slot positions with empty user-role messages.
+     * Ensures the messages array has the correct length from construction.
+     */
+    private initializeSlots;
+}
+//# sourceMappingURL=context-manager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-manager.d.ts","sourceRoot":"","sources":["../src/context-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAMvD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;IAC1C,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE;QACL,QAAQ,EAAE,YAAY,EAAE,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB;AAMD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA8B;IAC3D,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;;;;OAKG;gBACS,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,oBAAoB;IAoBnE;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,SAAS,MAAM,EAAE,CAE7B;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAa5C;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuBpC;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI1C;;;;OAIG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;;;;;;;;;;;OAYG;IACH,uBAAuB,IAAI,CAAC,OAAO,EAAE,YAAY,KAAK,YAAY;IAqBlE;;;OAGG;IACH,OAAO,CAAC,eAAe;CAUxB"}

package/dist/context-manager.js

@@ -0,0 +1,170 @@
+/**
+ * ContextManager: slot-based persistent context + ephemeral per-call injection.
+ *
+ * Manages the content an agent sees through two mechanisms:
+ * - **Slots**: Named content blocks at the start of the message array.
+ *   Persistent, updated immediately via setSlot(). Ordered by stability
+ *   (most stable first) for prefix cache optimization.
+ * - **Ephemeral context**: Per-call content injected via transformContext.
+ *   Never stored in agent.state.messages. Rebuilt every LLM call.
+ *
+ * Message array layout:
+ *   [SLOT REGION (0..N-1)] [CONVERSATION HISTORY] [EPHEMERAL (in transformContext)] [PROMPT]
+ *
+ * Reference: context-manager.md
+ */
+// ---------------------------------------------------------------------------
+// ContextManager
+// ---------------------------------------------------------------------------
+export class ContextManager {
+    agent;
+    slotNames;
+    slotIndexMap;
+    ephemeralContent = null;
+    /**
+     * Create a ContextManager.
+     *
+     * @param agent - The pi-agent-core Agent instance (or any object with state.messages)
+     * @param config - Configuration with ordered slot names
+     */
+    constructor(agent, config) {
+        this.agent = agent;
+        this.slotNames = Object.freeze([...config.slots]);
+        // Build index map: slot name -> position in messages array
+        const indexMap = new Map();
+        for (let i = 0; i < config.slots.length; i++) {
+            const name = config.slots[i];
+            if (indexMap.has(name)) {
+                throw new Error(`Duplicate slot name: "${name}"`);
+            }
+            indexMap.set(name, i);
+        }
+        this.slotIndexMap = indexMap;
+        // Initialize slot positions in the messages array with empty user-role messages.
+        // This ensures the array has the correct length from the start.
+        this.initializeSlots();
+    }
+    /**
+     * The number of context slots.
+     */
+    get slotCount() {
+        return this.slotNames.length;
+    }
+    /**
+     * The ordered slot names (frozen copy).
+     */
+    get slots() {
+        return this.slotNames;
+    }
+    /**
+     * Update a slot's content. Immediately updates the corresponding
+     * message in agent.state.messages at the slot's position.
+     *
+     * @param name - The slot name (must match a name from the config)
+     * @param content - The raw string content (consumer handles formatting)
+     * @throws Error if the slot name is not recognized
+     */
+    setSlot(name, content) {
+        const index = this.slotIndexMap.get(name);
+        if (index === undefined) {
+            throw new Error(`Unknown slot name: "${name}". Valid slots: ${[...this.slotIndexMap.keys()].join(', ')}`);
+        }
+        this.agent.state.messages[index] = {
+            role: 'user',
+            content,
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Read current slot content.
+     *
+     * @param name - The slot name
+     * @returns The slot's content string, or null if the slot has not been set
+     * @throws Error if the slot name is not recognized
+     */
+    getSlot(name) {
+        const index = this.slotIndexMap.get(name);
+        if (index === undefined) {
+            throw new Error(`Unknown slot name: "${name}". Valid slots: ${[...this.slotIndexMap.keys()].join(', ')}`);
+        }
+        const message = this.agent.state.messages[index];
+        if (!message) {
+            return null;
+        }
+        // Content can be a string or a content array
+        if (typeof message.content === 'string') {
+            return message.content;
+        }
+        // For content arrays, concatenate text parts
+        return message.content
+            .filter((part) => part.type === 'text' && typeof part.text === 'string')
+            .map((part) => part.text)
+            .join('');
+    }
+    /**
+     * Set ephemeral content for the next LLM call(s).
+     * Injected at the end of the message array inside the transformContext hook.
+     * Never written to agent.state.messages.
+     * Pass null to clear.
+     *
+     * @param content - The ephemeral content string, or null to clear
+     */
+    setEphemeral(content) {
+        this.ephemeralContent = content;
+    }
+    /**
+     * Get the current ephemeral content.
+     *
+     * @returns The ephemeral content, or null if not set
+     */
+    getEphemeral() {
+        return this.ephemeralContent;
+    }
+    /**
+     * Returns a transformContext hook function that appends ephemeral content.
+     *
+     * The hook is composable: the consumer can chain it with other transformContext
+     * logic (compaction, skill buffer, etc.).
+     *
+     * The ephemeral content is appended as a user-role message at the end of
+     * the messages array, after all conversation history but before the prompt.
+     * This placement ensures it does not invalidate the prefix cache for
+     * content above it.
+     *
+     * @returns A function suitable for use as a transformContext hook
+     */
+    getTransformContextHook() {
+        return (context) => {
+            if (this.ephemeralContent === null) {
+                return context;
+            }
+            // Append ephemeral content as a user-role message at the end
+            return {
+                ...context,
+                messages: [
+                    ...context.messages,
+                    {
+                        role: 'user',
+                        content: this.ephemeralContent,
+                        timestamp: Date.now(),
+                    },
+                ],
+            };
+        };
+    }
+    /**
+     * Initialize slot positions with empty user-role messages.
+     * Ensures the messages array has the correct length from construction.
+     */
+    initializeSlots() {
+        // Ensure the messages array exists and has at least slotCount entries
+        while (this.agent.state.messages.length < this.slotNames.length) {
+            this.agent.state.messages.push({
+                role: 'user',
+                content: '',
+                timestamp: 0,
+            });
+        }
+    }
+}
+//# sourceMappingURL=context-manager.js.map

package/dist/context-manager.js.map

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