@limo-labs/deity 0.1.0-alpha.0

package/dist/src/memory/memory-config.js

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import { TieredMemoryManager, } from "./tiered-memory.js";
+/**
+ * Zod schema for hot memory configuration validation.
+ * @since 2.0.0
+ */
+export const HotMemoryConfigSchema = z.object({
+    maxItems: z.number().int().positive(),
+    maxSize: z.number().int().positive().optional(),
+    ttl: z.number().int().positive().optional(),
+});
+/**
+ * Zod schema for warm storage configuration validation.
+ * @since 2.0.0
+ */
+export const WarmStorageConfigSchema = z.object({
+    enabled: z.boolean(),
+    maxSize: z.number().int().positive(),
+    compressionAlgorithm: z.enum(["gzip", "lz4", "none"]),
+    directory: z.string().min(1),
+});
+/**
+ * Zod schema for cold storage configuration validation.
+ * @since 2.0.0
+ */
+export const ColdStorageConfigSchema = z.object({
+    enabled: z.boolean(),
+    directory: z.string().min(1),
+});
+/**
+ * Zod schema for complete memory configuration validation.
+ * @since 2.0.0
+ */
+export const MemoryConfigSchema = z.object({
+    hot: HotMemoryConfigSchema,
+    warm: WarmStorageConfigSchema,
+    cold: ColdStorageConfigSchema,
+});
+/**
+ * Pre-configured memory settings for development environments.
+ *
+ * - Generous hot memory limits (2000 items, 200MB)
+ * - No compression (fast, no CPU overhead)
+ * - Warm and cold storage enabled
+ * - Short TTL for fast iteration
+ *
+ * @since 2.0.0
+ */
+export const MemoryPresets = {
+    /**
+     * Development preset: Fast and generous.
+     *
+     * Optimized for quick iteration and debugging with minimal overhead.
+     * Uses no compression for speed and has generous memory limits.
+     */
+    development: {
+        hot: {
+            maxItems: 2000,
+            maxSize: 200 * 1024 * 1024, // 200MB
+            ttl: 30 * 60 * 1000, // 30 minutes
+        },
+        warm: {
+            enabled: true,
+            maxSize: 2 * 1024 * 1024 * 1024, // 2GB
+            compressionAlgorithm: "none",
+            directory: ".deity/cache-dev",
+        },
+        cold: {
+            enabled: true,
+            directory: ".deity/archive-dev",
+        },
+    },
+    /**
+     * Production preset: Balanced and reliable.
+     *
+     * Optimized for production use with good balance between performance
+     * and resource usage. Uses gzip compression for space efficiency.
+     */
+    production: {
+        hot: {
+            maxItems: 1000,
+            maxSize: 100 * 1024 * 1024, // 100MB
+            ttl: 60 * 60 * 1000, // 1 hour
+        },
+        warm: {
+            enabled: true,
+            maxSize: 1024 * 1024 * 1024, // 1GB
+            compressionAlgorithm: "gzip",
+            directory: ".deity/cache",
+        },
+        cold: {
+            enabled: true,
+            directory: ".deity/archive",
+        },
+    },
+    /**
+     * Minimal preset: Lightweight with minimal disk usage.
+     *
+     * Optimized for resource-constrained environments or simple workflows.
+     * Warm storage disabled, only hot memory and cold storage used.
+     */
+    minimal: {
+        hot: {
+            maxItems: 500,
+            maxSize: 50 * 1024 * 1024, // 50MB
+            ttl: 10 * 60 * 1000, // 10 minutes
+        },
+        warm: {
+            enabled: false,
+            maxSize: 1, // Dummy value (warm is disabled)
+            compressionAlgorithm: "none",
+            directory: ".deity/cache",
+        },
+        cold: {
+            enabled: true,
+            directory: ".deity/archive",
+        },
+    },
+};
+/**
+ * Validates a memory configuration against the schema.
+ *
+ * Throws an error if the configuration is invalid.
+ *
+ * @param config - The configuration to validate
+ * @returns The validated configuration (typed)
+ * @throws {Error} If the configuration is invalid
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * try {
+ *   const validated = validateMemoryConfig(userConfig);
+ *   console.log("Configuration valid!");
+ * } catch (error) {
+ *   console.error("Invalid configuration:", error.message);
+ * }
+ * ```
+ */
+export function validateMemoryConfig(config) {
+    return MemoryConfigSchema.parse(config);
+}
+/**
+ * Merges a partial configuration with a base configuration.
+ *
+ * Useful for applying user overrides on top of a preset.
+ * Performs deep merge of nested objects.
+ *
+ * @param base - The base configuration (preset or default)
+ * @param override - The partial configuration to merge
+ * @returns The merged configuration
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * const config = mergeMemoryConfig(
+ *   MemoryPresets.production,
+ *   {
+ *     hot: { maxItems: 2000 }, // Override just maxItems
+ *   }
+ * );
+ * // Result: production preset with 2000 hot items instead of 1000
+ * ```
+ */
+export function mergeMemoryConfig(base, override) {
+    return {
+        hot: {
+            ...base.hot,
+            ...override.hot,
+        },
+        warm: {
+            ...base.warm,
+            ...override.warm,
+        },
+        cold: {
+            ...base.cold,
+            ...override.cold,
+        },
+    };
+}
+/**
+ * Creates a memory configuration from a preset or custom config.
+ *
+ * Supports three modes:
+ * 1. Preset name ("development", "production", "minimal")
+ * 2. Full custom configuration
+ * 3. Preset with overrides
+ *
+ * @param config - Preset name, full config, or preset with overrides
+ * @returns Validated memory configuration
+ * @throws {Error} If the configuration is invalid
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * // Use preset
+ * const config1 = createMemoryConfig("production");
+ *
+ * // Use custom config
+ * const config2 = createMemoryConfig({
+ *   hot: { maxItems: 1500 },
+ *   warm: { enabled: true, maxSize: 1024 * 1024 * 1024, compressionAlgorithm: "gzip", directory: ".cache" },
+ *   cold: { enabled: true, directory: ".archive" },
+ * });
+ *
+ * // Use preset with overrides
+ * const config3 = createMemoryConfig({
+ *   preset: "production",
+ *   override: { hot: { maxItems: 2000 } },
+ * });
+ * ```
+ */
+export function createMemoryConfig(config) {
+    // Case 1: Preset name
+    if (typeof config === "string") {
+        if (!(config in MemoryPresets)) {
+            throw new Error(`Unknown memory preset: "${config}". Valid presets: ${Object.keys(MemoryPresets).join(", ")}`);
+        }
+        return MemoryPresets[config];
+    }
+    // Case 2: Preset with override
+    if ("preset" in config && "override" in config) {
+        const base = MemoryPresets[config.preset];
+        return validateMemoryConfig(mergeMemoryConfig(base, config.override));
+    }
+    // Case 3: Full custom config
+    return validateMemoryConfig(config);
+}
+/**
+ * Gets the default memory configuration.
+ *
+ * Uses the production preset by default.
+ *
+ * @returns Default memory configuration
+ * @since 2.0.0
+ */
+export function getDefaultMemoryConfig() {
+    return MemoryPresets.production;
+}
+/**
+ * Creates a TieredMemoryManager instance from a memory configuration.
+ *
+ * Converts the user-facing MemoryConfig (with validation and presets) into
+ * the internal TieredMemoryConfig format and creates a TieredMemoryManager.
+ *
+ * This is a synchronous wrapper - it uses require() internally which works
+ * because TieredMemoryManager is in the same package.
+ *
+ * @param config - Memory configuration (preset name, full config, or preset with override)
+ * @returns Configured TieredMemoryManager instance (call .init() before use)
+ * @throws {Error} If the configuration is invalid
+ * @since 2.0.0
+ * @example
+ * ```typescript
+ * // Create from preset name
+ * const manager1 = createTieredMemoryManager("production");
+ * await manager1.init();
+ *
+ * // Create from custom config
+ * const manager2 = createTieredMemoryManager({
+ *   hot: { maxItems: 1000 },
+ *   warm: { enabled: true, maxSize: 1024 * 1024 * 1024, compressionAlgorithm: "gzip", directory: ".cache" },
+ *   cold: { enabled: true, directory: ".archive" },
+ * });
+ * await manager2.init();
+ *
+ * // Create from preset with overrides
+ * const manager3 = createTieredMemoryManager({
+ *   preset: "production",
+ *   override: { hot: { maxItems: 2000 } },
+ * });
+ * await manager3.init();
+ * ```
+ */
+export function createTieredMemoryManager(config) {
+    // Normalize to MemoryConfig
+    const memoryConfig = createMemoryConfig(config);
+    // Convert to TieredMemoryConfig (internal format)
+    const tieredConfig = {
+        hot: {
+            maxItems: memoryConfig.hot.maxItems,
+            maxSize: memoryConfig.hot.maxSize,
+            ttl: memoryConfig.hot.ttl,
+        },
+        warm: memoryConfig.warm.enabled
+            ? {
+                directory: memoryConfig.warm.directory,
+                maxSize: memoryConfig.warm.maxSize,
+                compressionAlgorithm: memoryConfig.warm.compressionAlgorithm,
+            }
+            : undefined,
+        cold: memoryConfig.cold.enabled
+            ? {
+                directory: memoryConfig.cold.directory,
+            }
+            : undefined,
+    };
+    return new TieredMemoryManager(tieredConfig);
+}
+//# sourceMappingURL=memory-config.js.map

package/dist/src/memory/memory-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-config.js","sourceRoot":"","sources":["../../../src/memory/memory-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,mBAAmB,GAEpB,MAAM,oBAAoB,CAAC;AAkF5B;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACrC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC/C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC5C,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACpC,oBAAoB,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACrD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7B,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,GAAG,EAAE,qBAAqB;IAC1B,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE,uBAAuB;CAC9B,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B;;;;;OAKG;IACH,WAAW,EAAE;QACX,GAAG,EAAE;YACH,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ;YACpC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;SACnC;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,MAAM;YACvC,oBAAoB,EAAE,MAAe;YACrC,SAAS,EAAE,kBAAkB;SAC9B;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,oBAAoB;SAChC;KACqB;IAExB;;;;;OAKG;IACH,UAAU,EAAE;QACV,GAAG,EAAE;YACH,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,EAAE,QAAQ;YACpC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,SAAS;SAC/B;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,MAAM;YACnC,oBAAoB,EAAE,MAAe;YACrC,SAAS,EAAE,cAAc;SAC1B;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,gBAAgB;SAC5B;KACqB;IAExB;;;;;OAKG;IACH,OAAO,EAAE;QACP,GAAG,EAAE;YACH,QAAQ,EAAE,GAAG;YACb,OAAO,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,OAAO;YAClC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,aAAa;SACnC;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,CAAC,EAAE,iCAAiC;YAC7C,oBAAoB,EAAE,MAAe;YACrC,SAAS,EAAE,cAAc;SAC1B;QACD,IAAI,EAAE;YACJ,OAAO,EAAE,IAAI;YACb,SAAS,EAAE,gBAAgB;SAC5B;KACqB;CAChB,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAe;IAClD,OAAO,kBAAkB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAkB,EAClB,QAAmC;IAEnC,OAAO;QACL,GAAG,EAAE;YACH,GAAG,IAAI,CAAC,GAAG;YACX,GAAG,QAAQ,CAAC,GAAG;SAChB;QACD,IAAI,EAAE;YACJ,GAAG,IAAI,CAAC,IAAI;YACZ,GAAG,QAAQ,CAAC,IAAI;SACjB;QACD,IAAI,EAAE;YACJ,GAAG,IAAI,CAAC,IAAI;YACZ,GAAG,QAAQ,CAAC,IAAI;SACjB;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAG+E;IAE/E,sBAAsB;IACtB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,MAAM,IAAI,aAAa,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,qBAAqB,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9F,CAAC;QACJ,CAAC;QACD,OAAO,aAAa,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,+BAA+B;IAC/B,IAAI,QAAQ,IAAI,MAAM,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC1C,OAAO,oBAAoB,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,6BAA6B;IAC7B,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAUD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,aAAa,CAAC,UAAU,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAG+E;IAE/E,4BAA4B;IAC5B,MAAM,YAAY,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAEhD,kDAAkD;IAClD,MAAM,YAAY,GAAuB;QACvC,GAAG,EAAE;YACH,QAAQ,EAAE,YAAY,CAAC,GAAG,CAAC,QAAQ;YACnC,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,OAAO;YACjC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG;SAC1B;QACD,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO;YAC7B,CAAC,CAAC;gBACE,SAAS,EAAE,YAAY,CAAC,IAAI,CAAC,SAAS;gBACtC,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO;gBAClC,oBAAoB,EAAE,YAAY,CAAC,IAAI,CAAC,oBAAoB;aAC7D;YACH,CAAC,CAAC,SAAS;QACb,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,OAAO;YAC7B,CAAC,CAAC;gBACE,SAAS,EAAE,YAAY,CAAC,IAAI,CAAC,SAAS;aACvC;YACH,CAAC,CAAC,SAAS;KACd,CAAC;IAEF,OAAO,IAAI,mBAAmB,CAAC,YAAY,CAAC,CAAC;AAC/C,CAAC"}

package/dist/src/memory/prefetcher.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Memory prefetcher for optimizing workflow execution.
+ *
+ * Analyzes workflow step dependencies and preloads data into hot memory
+ * before step execution to reduce latency.
+ *
+ * @module memory/prefetcher
+ * @since 2.0.0
+ */
+import type { Workflow } from "../workflow.js";
+import type { TieredMemoryManager } from "./tiered-memory.js";
+/**
+ * Dependency graph node representing a workflow step.
+ */
+interface DependencyNode {
+    stepId: string;
+    dependencies: Set<string>;
+}
+/**
+ * Prefetch hint for manual optimization.
+ */
+export interface PrefetchHint {
+    /** Step ID that will need this data */
+    stepId: string;
+    /** Keys to prefetch into hot memory */
+    keys: string[];
+}
+/**
+ * Memory prefetcher that analyzes workflow dependencies and preloads data.
+ *
+ * The prefetcher works by:
+ * 1. Analyzing which steps depend on outputs from previous steps
+ * 2. Before executing a step, promoting its dependencies to hot memory
+ * 3. Supporting manual prefetch hints for custom optimization
+ *
+ * @example
+ * ```typescript
+ * const prefetcher = new MemoryPrefetcher(memory, workflow);
+ *
+ * // Before executing Step2, prefetch Step1's output
+ * await prefetcher.prefetchForStep("Step2");
+ *
+ * // Manual prefetch with custom keys
+ * await prefetcher.prefetch({
+ *   stepId: "Step3",
+ *   keys: ["stage:Step1", "stage:Step2"]
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+export declare class MemoryPrefetcher {
+    private memory;
+    private workflow;
+    private dependencyGraph;
+    private prefetchHints;
+    constructor(memory: TieredMemoryManager, workflow: Workflow);
+    /**
+     * Build the dependency graph by analyzing workflow steps.
+     *
+     * This is a simple analysis - it assumes each step depends on all previous steps.
+     * More sophisticated analysis could inspect the buildPrompt() method to detect
+     * actual dependencies by checking for ctx.getOutput() calls.
+     */
+    private buildDependencyGraph;
+    /**
+     * Analyze dependencies for a specific step.
+     *
+     * Returns the set of step IDs that this step depends on.
+     *
+     * @param stepId - The step to analyze
+     * @returns Array of dependent step IDs
+     */
+    analyzeDependencies(stepId: string): string[];
+    /**
+     * Prefetch data for a specific step.
+     *
+     * Promotes all dependency outputs to hot memory before step execution.
+     * This is opportunistic - failures are logged but don't block execution.
+     *
+     * @param stepId - The step about to be executed
+     * @returns Promise that resolves when prefetch completes (or fails gracefully)
+     *
+     * @example
+     * ```typescript
+     * // Before executing Step2
+     * await prefetcher.prefetchForStep("Step2");
+     * // Now Step2 execution will find Step1 output in hot memory
+     * ```
+     */
+    prefetchForStep(stepId: string): Promise<void>;
+    /**
+     * Add a manual prefetch hint for a step.
+     *
+     * This allows developers to optimize specific steps by explicitly
+     * declaring what data they need.
+     *
+     * @param hint - Prefetch hint with step ID and keys
+     *
+     * @example
+     * ```typescript
+     * prefetcher.addHint({
+     *   stepId: "AnalyzeCode",
+     *   keys: ["stage:ReadFiles", "conversation:main"]
+     * });
+     * ```
+     */
+    addHint(hint: PrefetchHint): void;
+    /**
+     * Prefetch using a manual hint.
+     *
+     * @param hint - Prefetch hint with keys to load
+     */
+    prefetch(hint: PrefetchHint): Promise<void>;
+    /**
+     * Get the dependency graph for debugging.
+     *
+     * @returns Map of step IDs to their dependency nodes
+     */
+    getDependencyGraph(): Map<string, DependencyNode>;
+    /**
+     * Clear all prefetch hints.
+     */
+    clearHints(): void;
+    /**
+     * Get statistics about the dependency graph.
+     *
+     * @returns Stats about steps and dependencies
+     */
+    getStats(): {
+        totalSteps: number;
+        totalDependencies: number;
+        averageDependencies: number;
+    };
+}
+export {};
+//# sourceMappingURL=prefetcher.d.ts.map

package/dist/src/memory/prefetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetcher.d.ts","sourceRoot":"","sources":["../../../src/memory/prefetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D;;GAEG;AACH,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,eAAe,CAA8B;IACrD,OAAO,CAAC,aAAa,CAAwB;gBAEjC,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,QAAQ;IAU3D;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;;;;;OAOG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAS7C;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BpD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAKjC;;;;OAIG;IACG,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD;;;;OAIG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAIjD;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;;;OAIG;IACH,QAAQ,IAAI;QACV,UAAU,EAAE,MAAM,CAAC;QACnB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,mBAAmB,EAAE,MAAM,CAAC;KAC7B;CAcF"}

package/dist/src/memory/prefetcher.js

@@ -0,0 +1,186 @@
+/**
+ * Memory prefetcher for optimizing workflow execution.
+ *
+ * Analyzes workflow step dependencies and preloads data into hot memory
+ * before step execution to reduce latency.
+ *
+ * @module memory/prefetcher
+ * @since 2.0.0
+ */
+/**
+ * Memory prefetcher that analyzes workflow dependencies and preloads data.
+ *
+ * The prefetcher works by:
+ * 1. Analyzing which steps depend on outputs from previous steps
+ * 2. Before executing a step, promoting its dependencies to hot memory
+ * 3. Supporting manual prefetch hints for custom optimization
+ *
+ * @example
+ * ```typescript
+ * const prefetcher = new MemoryPrefetcher(memory, workflow);
+ *
+ * // Before executing Step2, prefetch Step1's output
+ * await prefetcher.prefetchForStep("Step2");
+ *
+ * // Manual prefetch with custom keys
+ * await prefetcher.prefetch({
+ *   stepId: "Step3",
+ *   keys: ["stage:Step1", "stage:Step2"]
+ * });
+ * ```
+ *
+ * @since 2.0.0
+ */
+export class MemoryPrefetcher {
+    memory;
+    workflow;
+    dependencyGraph;
+    prefetchHints;
+    constructor(memory, workflow) {
+        this.memory = memory;
+        this.workflow = workflow;
+        this.dependencyGraph = new Map();
+        this.prefetchHints = new Map();
+        // Build dependency graph on initialization
+        this.buildDependencyGraph();
+    }
+    /**
+     * Build the dependency graph by analyzing workflow steps.
+     *
+     * This is a simple analysis - it assumes each step depends on all previous steps.
+     * More sophisticated analysis could inspect the buildPrompt() method to detect
+     * actual dependencies by checking for ctx.getOutput() calls.
+     */
+    buildDependencyGraph() {
+        const steps = this.workflow.steps;
+        for (let i = 0; i < steps.length; i++) {
+            const step = steps[i];
+            const dependencies = new Set();
+            // Assume step depends on all previous steps
+            // (This is conservative but safe)
+            for (let j = 0; j < i; j++) {
+                dependencies.add(steps[j].id);
+            }
+            this.dependencyGraph.set(step.id, {
+                stepId: step.id,
+                dependencies,
+            });
+        }
+    }
+    /**
+     * Analyze dependencies for a specific step.
+     *
+     * Returns the set of step IDs that this step depends on.
+     *
+     * @param stepId - The step to analyze
+     * @returns Array of dependent step IDs
+     */
+    analyzeDependencies(stepId) {
+        const node = this.dependencyGraph.get(stepId);
+        if (!node) {
+            return [];
+        }
+        return Array.from(node.dependencies);
+    }
+    /**
+     * Prefetch data for a specific step.
+     *
+     * Promotes all dependency outputs to hot memory before step execution.
+     * This is opportunistic - failures are logged but don't block execution.
+     *
+     * @param stepId - The step about to be executed
+     * @returns Promise that resolves when prefetch completes (or fails gracefully)
+     *
+     * @example
+     * ```typescript
+     * // Before executing Step2
+     * await prefetcher.prefetchForStep("Step2");
+     * // Now Step2 execution will find Step1 output in hot memory
+     * ```
+     */
+    async prefetchForStep(stepId) {
+        const dependencies = this.analyzeDependencies(stepId);
+        // Build list of keys to prefetch
+        const keysToFetch = [];
+        // Add dependency step outputs
+        for (const depId of dependencies) {
+            keysToFetch.push(`stage:${depId}`);
+        }
+        // Add manual hints if any
+        const hints = this.prefetchHints.get(stepId);
+        if (hints) {
+            keysToFetch.push(...hints);
+        }
+        // Prefetch all keys (opportunistically, don't fail on errors)
+        await Promise.allSettled(keysToFetch.map(async (key) => {
+            try {
+                await this.memory.promote(key);
+            }
+            catch (error) {
+                // Prefetch failure is not critical - log and continue
+                console.warn(`Prefetch failed for key "${key}":`, error);
+            }
+        }));
+    }
+    /**
+     * Add a manual prefetch hint for a step.
+     *
+     * This allows developers to optimize specific steps by explicitly
+     * declaring what data they need.
+     *
+     * @param hint - Prefetch hint with step ID and keys
+     *
+     * @example
+     * ```typescript
+     * prefetcher.addHint({
+     *   stepId: "AnalyzeCode",
+     *   keys: ["stage:ReadFiles", "conversation:main"]
+     * });
+     * ```
+     */
+    addHint(hint) {
+        const existing = this.prefetchHints.get(hint.stepId) || [];
+        this.prefetchHints.set(hint.stepId, [...existing, ...hint.keys]);
+    }
+    /**
+     * Prefetch using a manual hint.
+     *
+     * @param hint - Prefetch hint with keys to load
+     */
+    async prefetch(hint) {
+        this.addHint(hint);
+        await this.prefetchForStep(hint.stepId);
+    }
+    /**
+     * Get the dependency graph for debugging.
+     *
+     * @returns Map of step IDs to their dependency nodes
+     */
+    getDependencyGraph() {
+        return new Map(this.dependencyGraph);
+    }
+    /**
+     * Clear all prefetch hints.
+     */
+    clearHints() {
+        this.prefetchHints.clear();
+    }
+    /**
+     * Get statistics about the dependency graph.
+     *
+     * @returns Stats about steps and dependencies
+     */
+    getStats() {
+        const totalSteps = this.dependencyGraph.size;
+        let totalDependencies = 0;
+        for (const node of this.dependencyGraph.values()) {
+            totalDependencies += node.dependencies.size;
+        }
+        return {
+            totalSteps,
+            totalDependencies,
+            averageDependencies: totalSteps > 0 ? totalDependencies / totalSteps : 0,
+        };
+    }
+}
+//# sourceMappingURL=prefetcher.js.map

package/dist/src/memory/prefetcher.js.map

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